HAL ETH functions ¶

ETH initialization and deInitialization functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Exported_Functions_Group1

This subsection provides functions allowing to initialize and de-initialize the ETHx instance:

HAL_ETH_Init(): Initialize the selected ETHx instance
- All software resources are initialized
- No hardware initialization is performed at this level.
HAL_ETH_DeInit(): Restore the default configuration of the selected ETHx instance.

Functions

hal_status_t HAL_ETH_Init ( hal_eth_handle_t * heth , hal_eth_t instance ) ¶

Initialize the Ethernet HAL handle and peripheral instance.

This function initializes the Ethernet HAL context referenced by heth for the given Ethernet peripheral instance. It:

Stores the hardware instance in the handle.
Enables the Ethernet clocks (if the clock enable model requires it).
Initializes common, TX, and RX callbacks to their default implementations (when callback registration is enabled).
Creates the OS semaphore used for bus protection (when mutex support is enabled).
Clears optional user data and last error codes.
Initializes all TX/RX channels to the reset/unlocked state.
Sets the global state to HAL_ETH_STATE_INIT.

This function does not configure pins, descriptors, or low-level MAC, DMA or MTL parameters; those are typically handled by separate configuration APIs.

See also

HAL_ETH_DeInit

Note

When USE_HAL_ETH_CLK_ENABLE_MODEL is configured to be greater than or equal to HAL_CLK_ENABLE_PERIPH_ONLY, this function enables the Ethernet clocks via HAL_RCC_ETH1_EnableClock and related functions.

Note

When USE_HAL_ETH_REGISTER_CALLBACKS is enabled, this function sets common, TX, and RX callbacks to their default handlers.

Note

The caller must perform further configuration (descriptors, DMA, MAC, MTL, interrupts, pins) before starting traffic.

Parameters :

heth – [inout] Pointer to an hal_eth_handle_t structure that will be initialized. On successful return, its fields (instance, channels, callbacks, semaphore, state, etc.) are prepared for further configuration and use.
instance – [in] Ethernet peripheral instance identifier. Must correspond to a valid ETH_TypeDef instance and satisfy IS_ETH_ALL_INSTANCE.

Return values :

HAL_OK – Initialization succeeded; the handle is now in HAL_ETH_STATE_INIT state.
HAL_ERROR – OS semaphore creation failed (when USE_HAL_MUTEX == 1).
HAL_INVALID_PARAM – heth is NULL (only when parameter checking is enabled via USE_HAL_CHECK_PARAM).

Pre :

The system clock tree must be fully configured and provide a valid clock to the Ethernet peripheral before calling this function.

void HAL_ETH_DeInit ( hal_eth_handle_t * heth ) ¶

De-initialize the Ethernet peripheral.

This function de-initializes the Ethernet HAL context referenced by heth and resets the software state of all TX/RX channels. It also disables the Ethernet peripheral clocks and deletes the associated OS semaphore if these features are enabled.

The function performs the following actions:

Clears optional user data and last error codes stored in the handle.
Iterates over all TX channels:
- Stops any channel that is in HAL_ETH_CHANNEL_STATE_ACTIVE or HAL_ETH_CHANNEL_STATE_SUSPENDED.
- Resets the channel state to HAL_ETH_CHANNEL_STATE_RESET.
- Unlocks the channel (ETH_CHANNEL_STATE_UNLOCKED).
- Clears the TX-complete callback pointer.
Iterates over all RX channels:
- Stops any channel that is in HAL_ETH_CHANNEL_STATE_ACTIVE or HAL_ETH_CHANNEL_STATE_SUSPENDED.
- Resets the channel state to HAL_ETH_CHANNEL_STATE_RESET.
- Unlocks the channel (ETH_CHANNEL_STATE_UNLOCKED).
- Clears the RX-complete and RX-allocate callback pointers.
Sets the global state of the handle to HAL_ETH_STATE_RESET.
Disables the Ethernet clocks if USE_HAL_ETH_CLK_ENABLE_MODEL is configured to at least HAL_CLK_ENABLE_PERIPH_ONLY.
Deletes the OS semaphore associated with the handle if USE_HAL_MUTEX is enabled.

Note

This function does not free user-allocated memory for descriptors or buffers; it only resets the HAL state and disables clocks and synchronization primitives tied to the handle.

Note

After this function returns, heth is in the HAL_ETH_STATE_RESET state and must be reinitialized via the dedicated initialization function before being used again.

Warning

This function is not thread-safe. Ensure that no concurrent call to this function is made while it is executing.

Parameters :: heth – [inout] Pointer to an hal_eth_handle_t structure that contains the configuration information and runtime state for the Ethernet peripheral. Its internal fields (channels, callbacks, user data, error codes, semaphore, clocks) are reset/de-initialized by this function.

ETH peripheral configuration functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Exported_Functions_Group2

This subsection provides functions allowing to configure the Ethernet peripheral:

HAL_ETH_SetConfig(): Configure the selected ETHx instance.
HAL_ETH_GetConfig(): Retrieve the current configuration of the selected ETHx instance.

Functions

hal_status_t HAL_ETH_SetConfig ( hal_eth_handle_t * heth , const hal_eth_config_t * p_config ) ¶

Configure the Ethernet MAC, MTL and DMA according to the given settings.

This function applies a complete basic configuration of the Ethernet peripheral using the parameters provided in p_config and the handle heth. It:

Checks that the handle is in a valid state (HAL_ETH_STATE_INIT or HAL_ETH_STATE_CONFIGURED).
Selects and configures the media interface (MII/RMII/RGMII) through RCC/SBS.
Performs a software reset of the MAC subsystem and waits for completion.
Configures the MDIO clock range according to the current HCLK.
Initializes MAC, MTL and DMA blocks with default settings.
Initializes all TX and RX DMA/MTL channels with default configuration.
Programs the primary MAC address (MACA0) from p_config->mac_addr.
Masks MMC TX/RX interrupts.

See also

HAL_ETH_Init

Note

This function performs a MAC software reset; any previous runtime configuration in MAC/MTL/DMA registers is lost.

Note

The function masks a set of MMC TX/RX interrupts by default.

Parameters :

heth – [inout] Pointer to an hal_eth_handle_t structure that contains the configuration information for the Ethernet peripheral. Its global_state is updated to HAL_ETH_STATE_CONFIGURED on success or reverted to HAL_ETH_STATE_INIT on SW reset failure.
p_config – [in] Pointer to a constant hal_eth_config_t structure containing:
- media_interface: media interface selection (hal_eth_media_interface_t for supported values).
- mac_addr[6] : 6-byte MAC address to be programmed into MACA0 register (index 0 = lowest byte).

Return values :

HAL_OK – Configuration completed successfully.
HAL_ERROR – Timeout occurred while waiting for the software reset bit to clear.
HAL_INVALID_PARAM – heth or p_config is NULL (only when parameter checking is enabled via USE_HAL_CHECK_PARAM).

Pre :

heth must have been initialized with HAL_ETH_Init.
heth->global_state must be either HAL_ETH_STATE_INIT or HAL_ETH_STATE_CONFIGURED (checked with debug and optional runtime checks).

void HAL_ETH_GetConfig ( const hal_eth_handle_t * heth , hal_eth_config_t * p_config ) ¶

Retrieve the current Ethernet configuration (media interface and MAC address).

This function reads back the hardware configuration of the Ethernet peripheral associated with heth and fills the hal_eth_config_t structure pointed to by p_config.

It:

Reads the media interface configuration from RCC or SBS (depending on the product) and sets p_config->media_interface to one of supported values in hal_eth_media_interface_t.
Reads the primary MAC address (MACA0) from MACA0LR and MACA0HR registers and writes it into p_config->mac_addr[0..5].

See also

HAL_ETH_SetConfig

Note

This function does not perform any hardware reconfiguration; it only reads the current registers and copies their values into p_config.

Note

The content of p_config can later be passed to HAL_ETH_SetConfig() to re-apply or modify the configuration.

Parameters :

heth – [in] Pointer to a constant hal_eth_handle_t structure that contains the Ethernet peripheral instance and state. Its global_state must be HAL_ETH_STATE_CONFIGURED.
p_config – [out] Pointer to a hal_eth_config_t structure where the current configuration will be stored (media interface and MAC address).

Pre :

heth must not be NULL.
p_config must not be NULL.
heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED (checked with debug and optional runtime checks).

ETH peripheral sub-blocks configuration functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Exported_Functions_Group3

This subsection provides functions allowing to configure the Ethernet Sub-Blocks:

MAC sub-block:
- HAL_ETH_MAC_SetConfig(): Configure the MAC sub-block for selected ETHx instance.
- HAL_ETH_MAC_GetConfig(): Retrieve the current configuration of MAC sub-block for selected ETHx instance.
DMA sub-block:
- HAL_ETH_DMA_SetConfig(): Configure the DMA sub-block for selected ETHx instance.
- HAL_ETH_DMA_GetConfig(): Retrieve the current configuration of DMA sub-block for selected ETHx instance.
MTL sub-block:
- HAL_ETH_MTL_SetConfig(): Configure the MTL sub-block for selected ETHx instance.
- HAL_ETH_MTL_GetConfig(): Retrieve the current configuration of MTL sub-block for selected ETHx instance.

Functions

void HAL_ETH_MAC_GetConfig ( const hal_eth_handle_t * heth , hal_eth_mac_config_t * p_macconf ) ¶

Retrieve the current MAC configuration from the ETH peripheral.

This function reads the MAC control and extended control registers of the Ethernet peripheral associated to heth and fills the p_macconf structure with the current hardware configuration.

The retrieved configuration includes, but is not limited to:

Link configuration: speed and duplex mode.
Loopback mode.
Source address control.
Inter-packet gap (IPG) settings.
Back-off limit.
Preamble length.
Giant packet size limit and related control.
2K packet support.
CRC strip and pad/CRC strip controls.
TX jabber timer control.
Carrier sense (CS) before/during transmit controls.
Retry transmission control.
RX watchdog timer, RX jumbo packet, and RX checksum offload controls.
RX receive own control.
RX CRC checking control.
Deferral check control.
Slow protocol (unicast and general) detection controls.
Extended inter-packet gap control and value.
Programmable watchdog control and timeout.
Flow control configuration (TX pause time, zero-quanta pause, pause. low threshold, TX/RX flow control, unicast pause packet detection).
Optional packet burst mode (when not in fast-only operation).

Note

This API only queries the hardware registers. It does not modify any MAC configuration.

Note

The Ethernet HAL handle heth must be in the HAL_ETH_STATE_CONFIGURED state when calling this function; otherwise an assertion can be raised in debug builds.

Parameters :

heth – [in] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_macconf – [out] Pointer to a hal_eth_mac_config_t structure that will be filled with the current MAC configuration read from the hardware registers.

Pre :

heth must not be NULL.

Pre :

p_macconf must not be NULL.

Pre :

heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

hal_status_t HAL_ETH_MAC_SetConfig ( hal_eth_handle_t * heth , const hal_eth_mac_config_t * p_macconf ) ¶

Set the MAC configuration for the ETH peripheral.

This function programs the Ethernet MAC configuration registers of the peripheral associated with heth according to the parameters provided in p_macconf.

The configuration covers, among others:

Link configuration: speed and duplex mode.
Loopback mode.
Source address control.
Inter-packet gap (IPG) settings.
Back-off limit.
Preamble length.
Giant packet size limit and related control.
2K packet support.
CRC strip and pad/CRC strip controls.
TX jabber timer control.
Carrier sense (CS) before/during transmit controls.
Retry transmission control.
RX watchdog timer, RX jumbo packet, and RX checksum offload controls.
RX receive own control.
RX CRC checking control.
Deferral check control.
Slow protocol (unicast and general) detection controls.
Extended inter-packet gap control and value.
Programmable watchdog control and timeout.
Flow control configuration (TX pause time, zero-quanta pause, pause. low threshold, TX/RX flow control, unicast pause packet detection).
Optional packet burst mode (when not in fast-only operation).

All fields of p_macconf are checked for validity using the corresponding parameter-check macros (e.g. IS_ETH_MAC_SPEED, IS_ETH_MAC_DUPLEX_MODE, etc.) in debug builds. If any field is invalid, an assertion can be raised.

This API requires that the Ethernet HAL handle is already in the HAL_ETH_STATE_CONFIGURED state. It does not change the global state of heth and does not start or stop the MAC; it only updates the configuration registers.

Note

In this implementation, invalid parameters are primarily handled via debug assertions. When USE_HAL_CHECK_PARAM is enabled, a HAL_INVALID_PARAM status can be returned when p_macconf is NULL.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_macconf – [in] Pointer to a constant hal_eth_mac_config_t structure that holds the MAC configuration to be applied to the hardware.

Return values :

HAL_OK – MAC configuration has been successfully applied.
HAL_INVALID_PARAM –
- p_macconf is NULL when USE_HAL_CHECK_PARAM is enabled, or
- One or more fields of p_macconf are invalid (only if your implementation uses this status in addition to assertions).

Pre :

heth must not be NULL.

Pre :

p_macconf must not be NULL.

Pre :

heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

void HAL_ETH_DMA_GetConfig ( const hal_eth_handle_t * heth , hal_eth_dma_config_t * p_dmaconf ) ¶

Get the DMA configuration of the ETH peripheral.

This function reads the DMA-related registers of the Ethernet peripheral associated with heth and fills the p_dmaconf structure with the current hardware configuration.

The retrieved configuration includes (depending on the build-time options and system bus type):

TX/RX transfer arbitration algorithm.
Address-aligned beats enable/disable.
DMA burst mode configuration.
Maximum bus burst length (in beats).
System Bus configurations (OSR limits or Mixed burst and rebuild increment burst).
DMA transfer priority configuration.

Note

This API only queries the DMA configuration registers. It does not modify any configuration or DMA state.

Note

The Ethernet HAL handle heth must be in the HAL_ETH_STATE_CONFIGURED state when calling this function; otherwise an assertion is raised in debug builds.

Parameters :

heth – [in] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_dmaconf – [out] Pointer to a hal_eth_dma_config_t structure that will be filled with the current DMA configuration read from the hardware registers.

Pre :

heth must not be NULL.

Pre :

p_dmaconf must not be NULL.

Pre :

heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

hal_status_t HAL_ETH_DMA_SetConfig ( hal_eth_handle_t * heth , const hal_eth_dma_config_t * p_dmaconf ) ¶

Set the DMA configuration of the ETH peripheral.

This function programs the DMA-related registers of the Ethernet peripheral associated with heth according to the parameters provided in p_dmaconf.

The configuration can include (depending on the build-time options and system bus type):

TX/RX transfer arbitration algorithm.
Address-aligned beats control.
DMA burst length mode.
Maximum bus burst length (in beats).
System Bus configurations (OSR limits or Mixed burst and rebuild increment burst).
DMA transfer priority configuration.

All fields of p_dmaconf are checked for validity using the corresponding parameter-check macros (for example, IS_ETH_DMA_TR_ARBITRATION_ALGO, IS_ETH_DMA_ADDR_ALIGNED_BEATS, IS_ETH_DMA_BURST_LEN_MODE, etc.) in debug builds. If any field is invalid, an assertion is raised.

This API requires that the Ethernet HAL handle is already in the HAL_ETH_STATE_CONFIGURED state. It does not change the global state of heth and does not start or stop the DMA; it only updates the DMA configuration registers.

Note

In this implementation, most invalid parameters are handled via debug assertions. When USE_HAL_CHECK_PARAM is enabled, a HAL_INVALID_PARAM status is returned if p_dmaconf is NULL.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_dmaconf – [in] Pointer to a constant hal_eth_dma_config_t structure that holds the DMA configuration to be applied to the hardware.

Return values :

HAL_OK – DMA configuration has been successfully applied.
HAL_INVALID_PARAM –
- p_dmaconf is NULL when USE_HAL_CHECK_PARAM is enabled.

Pre :

heth must not be NULL.

Pre :

p_dmaconf must not be NULL.

Pre :

heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

void HAL_ETH_MTL_GetConfig ( const hal_eth_handle_t * heth , hal_eth_mtl_config_t * p_mtlconf ) ¶

Get the MTL configuration of the ETH peripheral.

This function reads the MTL (MAC Transmission Layer) related registers of the Ethernet peripheral associated with heth and fills the p_mtlconf structure with the current hardware configuration.

The retrieved configuration can include (depending on the build-time options):

TX scheduling algorithm configuration.
RX arbitration algorithm configuration.
TX forward status control (forwarding behavior when store-and-forward conditions are not fully met).

Note

This API only queries the MTL configuration registers. It does not modify any configuration or MTL state.

Note

The Ethernet HAL handle heth must be in the HAL_ETH_STATE_CONFIGURED state when calling this function; otherwise an assertion can be raised in debug builds.

Parameters :

heth – [in] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_mtlconf – [out] Pointer to a hal_eth_mtl_config_t structure that will be filled with the current MTL configuration read from the hardware registers.

Pre :

heth must not be NULL.

Pre :

p_mtlconf must not be NULL.

Pre :

heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

hal_status_t HAL_ETH_MTL_SetConfig ( hal_eth_handle_t * heth , const hal_eth_mtl_config_t * p_mtlconf ) ¶

Set the MTL configuration of the ETH peripheral.

This function programs the MTL (MAC Transmission Layer) related registers of the Ethernet peripheral associated with heth according to the parameters provided in p_mtlconf.

The configuration can include (depending on the build-time options):

TX scheduling algorithm configuration.
RX arbitration algorithm configuration.
TX forward status control (forwarding behavior when store-and-forward conditions are not fully met).

All fields of p_mtlconf are checked for validity using the corresponding parameter-check macros (for example, IS_ETH_MTL_TX_SCHEDULING_ALGO, IS_ETH_MTL_RX_ARBITRATION_ALGO, IS_ETH_MTL_TX_FWD_STATUS_CTRL) in debug builds. If any field is invalid, an assertion can be raised.

This API requires that the Ethernet HAL handle is already in the HAL_ETH_STATE_CONFIGURED state. It does not change the global state of heth and does not start or stop the MTL; it only updates the MTL configuration registers.

Note

In this implementation, most invalid parameters are handled via debug assertions. When USE_HAL_CHECK_PARAM is enabled, a HAL_INVALID_PARAM status is returned if p_mtlconf is NULL.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_mtlconf – [in] Pointer to a constant hal_eth_mtl_config_t structure that holds the MTL configuration to be applied to the hardware.

Return values :

HAL_OK – MTL configuration has been successfully applied.
HAL_INVALID_PARAM –
- p_mtlconf is NULL when USE_HAL_CHECK_PARAM is enabled.

Pre :

heth must not be NULL.

Pre :

p_mtlconf must not be NULL.

Pre :

heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

ETH channels configuration functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Exported_Functions_Group4

This subsection provides functions allowing to configure the Ethernet Channels:

HAL_ETH_SetConfigTxChannel(): Configure the selected Tx ETHx Channel.
HAL_ETH_SetConfigRxChannel(): Configure the selected Rx ETHx Channel.
HAL_ETH_GetConfigTxChannel(): Retrieve the current configuration of the selected Tx ETHx Channel.
HAL_ETH_GetConfigRxChannel(): Retrieve the current configuration of the selected Rx ETHx Channel.
HAL_ETH_GetChannelAllocNeeds(): Retrieve Memory Allocation Needs (requirements) for the selected Tx/Rx ETHx Channel.

Functions

hal_status_t HAL_ETH_SetConfigTxChannel ( hal_eth_handle_t * heth , uint32_t channel , const hal_eth_tx_channel_config_t * p_chconf ) ¶

Set the configuration for a Tx channel.

This function configures a given Ethernet Tx channel and its associated MTL Tx queue and DMA Tx channel according to the parameters provided in p_chconf.

The configuration includes:

DMA Tx channel configuration (PBL x8 mode, burst length, second-packet operate control, and descriptor alignment requirements).
MTL Tx queue configuration (operating mode, queue size, transmit mode, and, when supported, queue average (AV) algorithm).
FIFO event configuration (event mode and event parameters).
Maximum number of application buffers associated with this channel.

The function also:

Validates the channel index and Tx channel parameters.
Checks and aligns the descriptor size to the requested alignment.
Updates the internal Tx channel state to HAL_ETH_CHANNEL_STATE_CONFIGURED when successful.

Note

In this implementation, most invalid parameters are handled via debug assertions. When USE_HAL_CHECK_PARAM is enabled, a HAL_INVALID_PARAM status is returned if p_chconf is NULL or channel is invalid, or if descriptor alignment fails.

Note

The internal descriptor ring size is multiplied by ETH_MAX_DESC_PER_APP_BUF_CNT to account for both context descriptors and data descriptors.Therefore, the application can start the channel with a descriptor ring size that differs from the size implied by p_chconf->max_app_buffers_num.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
channel – [in] Channel index to be configured, as defined by IS_ETH_CHANNEL_TX_INDEX.
p_chconf – [in] Pointer to a constant hal_eth_tx_channel_config_t structure that holds the Tx channel configuration to be applied.

Return values :

HAL_OK – Tx channel configuration has been successfully applied.
HAL_INVALID_PARAM –
- p_chconf is NULL when USE_HAL_CHECK_PARAM is enabled.
- channel is invalid when USE_HAL_CHECK_PARAM is enabled.
- The requested descriptor alignment cannot be satisfied by the DMA descriptor size alignment constraints.

Pre :

heth must not be NULL.

Pre :

p_chconf must not be NULL.

Pre :

channel must be a valid Tx channel index (see IS_ETH_CHANNEL_TX_INDEX).

Pre :

heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

Pre :

The Tx channel state must be HAL_ETH_CHANNEL_STATE_RESET or HAL_ETH_CHANNEL_STATE_CONFIGURED.

hal_status_t HAL_ETH_SetConfigRxChannel ( hal_eth_handle_t * heth , uint32_t channel , const hal_eth_rx_channel_config_t * p_chconf ) ¶

Set the configuration for a Rx channel.

This function configures a given Ethernet Rx channel and its associated MTL Rx queue and DMA Rx channel according to the parameters provided in p_chconf.

The configuration includes:

DMA Rx channel configuration (burst length, buffer length, and descriptor alignment requirements).
MTL Rx queue configuration (operating mode, queue size, checksum error drop behavior, forwarding of error and undersized packets, and receive queue mode).
Mapping of the MTL Rx queue to a DMA channel when multiple Rx channels are supported.
FIFO event configuration (event mode and event parameters).
Maximum number of application buffers associated with this channel.

The function also:

Validates the channel index and Rx channel parameters.
Ensures the Rx buffer length is aligned to the bus data width (ETH_BUS_DATA_WIDTH_BYTE).
Checks and aligns the descriptor size to the requested alignment.
Updates the internal Rx channel state to HAL_ETH_CHANNEL_STATE_CONFIGURED when successful.

Note

In this implementation, most invalid parameters are handled via debug assertions. When USE_HAL_CHECK_PARAM is enabled, a HAL_INVALID_PARAM status is returned if p_chconf is NULL, channel is invalid, or if buffer or descriptor alignment checks fail.

Note

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
channel – [in] Channel index to be configured, as defined by IS_ETH_CHANNEL_RX_INDEX.
p_chconf – [in] Pointer to a constant hal_eth_rx_channel_config_t structure that holds the Rx channel configuration to be applied.

Return values :

HAL_OK – Rx channel configuration has been successfully applied.
HAL_INVALID_PARAM –
- p_chconf is NULL when USE_HAL_CHECK_PARAM is enabled.
- channel is invalid when USE_HAL_CHECK_PARAM is enabled.
- The Rx buffer length is not aligned to ETH_BUS_DATA_WIDTH_BYTE.
- The requested descriptor alignment cannot be satisfied by the DMA descriptor size alignment constraints.

Pre :

heth must not be NULL.

Pre :

p_chconf must not be NULL.

Pre :

channel must be a valid Rx channel index (see IS_ETH_CHANNEL_RX_INDEX).

Pre :

heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

Pre :

The Rx channel state must be HAL_ETH_CHANNEL_STATE_RESET or HAL_ETH_CHANNEL_STATE_CONFIGURED.

void HAL_ETH_GetConfigTxChannel ( const hal_eth_handle_t * heth , uint32_t channel , hal_eth_tx_channel_config_t * p_chconf ) ¶

Get the configuration for a Tx channel.

This function retrieves the configuration of a given Ethernet Tx channel, including the associated MTL Tx queue and DMA Tx channel, and stores it in the structure pointed to by p_chconf.

The retrieved configuration includes:

Descriptor-related settings (maximum number of application buffers and descriptor size alignment).
FIFO event configuration (event mode and event parameters).
DMA Tx channel configuration.
MTL Tx queue configuration.

Parameters :

heth – [in] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
channel – [in] Channel index whose configuration is requested, as defined by IS_ETH_CHANNEL_TX_INDEX.
p_chconf – [out] Pointer to a hal_eth_tx_channel_config_t structure that will be filled with the current Tx channel configuration.

Pre :

heth must not be NULL.

Pre :

p_chconf must not be NULL.

Pre :

channel must be a valid Tx channel index (see IS_ETH_CHANNEL_TX_INDEX).

Pre :

heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

void HAL_ETH_GetConfigRxChannel ( const hal_eth_handle_t * heth , uint32_t channel , hal_eth_rx_channel_config_t * p_chconf ) ¶

Get the configuration for a Rx channel.

This function retrieves the configuration of a given Ethernet Rx channel, including the associated MTL Rx queue and DMA Rx channel, and stores it in the structure pointed to by p_chconf.

The retrieved configuration includes:

Descriptor-related settings (maximum number of application buffers and descriptor size alignment).
FIFO event configuration (event mode and event parameters).
DMA Rx channel configuration.
MTL Rx queue configuration.

Parameters :

heth – [in] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
channel – [in] Channel index whose configuration is requested, as defined by IS_ETH_CHANNEL_RX_INDEX.
p_chconf – [out] Pointer to a hal_eth_rx_channel_config_t structure that will be filled with the current Rx channel configuration.

Pre :

heth must not be NULL.

Pre :

p_chconf must not be NULL.

Pre :

channel must be a valid Rx channel index (see IS_ETH_CHANNEL_RX_INDEX).

Pre :

heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

void HAL_ETH_GetChannelAllocNeeds ( const hal_eth_handle_t * heth , uint32_t channel , hal_eth_channel_alloc_needs_t * p_ch_alloc_req ) ¶

Get the memory allocation requirements for a channel.

This function returns the memory size and alignment requirements for the descriptor ring associated with a given Ethernet channel (Tx or Rx), and stores them in the structure pointed to by p_ch_alloc_req.

The function determines whether the specified channel is a Tx or Rx channel, retrieves the corresponding internal channel context, and computes:

The total memory size in bytes required for the descriptor ring.
The required memory address alignment in bytes.

The size is computed as:

                   mem_size_byte = total_desc_cnt * desc_len_byte.

                  

and the alignment is set to ETH_BUS_DATA_WIDTH_BYTE.

Note

The values of desc_len_byte and total_desc_cnt depend on the channel configuration, in particular on whether the extended format and/or context descriptors are expected to be used.

Parameters :

heth – [in] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
channel – [in] Channel index, as defined by IS_ETH_CHANNEL_INDEX. The function automatically distinguishes between Tx and Rx channels using HAL_ETH_TX_CHANNEL_ALL.
p_ch_alloc_req – [out] Pointer to a hal_eth_channel_alloc_needs_t structure that will be filled with the memory allocation requirements.

Pre :

heth must not be NULL.

Pre :

p_ch_alloc_req must not be NULL.

Pre :

channel must be a valid channel index (see IS_ETH_CHANNEL_INDEX).

Pre :

The corresponding Tx or Rx channel state must be HAL_ETH_CHANNEL_STATE_CONFIGURED.

ETH peripheral optional control functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Exported_Functions_Group5

This subsection provides functions allowing the control of the Ethernet Peripheral Features:

MAC Update Link Config : provides functions allowing update the speed/duplex without resetting the MAC.
- HAL_ETH_UpdateConfigLink(): Update the MAC speed and duplex mode.
MAC ARP offload Feature: provides functions allowing the control of the Ethernet ARP Offloading Feature.
- HAL_ETH_EnableARPOffload(): Enable ARP offload.
- HAL_ETH_DisableARPOffload(): Disable ARP offload.
- HAL_ETH_IsEnabledARPOffload(): Check if the ETH ARP offload is enabled.
- HAL_ETH_SetARPTargetIP(): Set ARP target IP address.
MAC LPM Feature: provides functions allowing the control of the Ethernet LPM Feature.
- HAL_ETH_EnterPowerDownMode(): Enters Ethernet Power Down mode with specified PMT control flags.
- HAL_ETH_ExitPowerDownMode(): Exit power down mode.
- HAL_ETH_SetRemoteWakeUpPcktFilter(): Configures the Remote Wake-Up Packet Filter LUT for Ethernet.
EEE Features: provides functions allowing the control of the Ethernet EEE Feature.
- HAL_ETH_EnterLPIMode(): Configures Ethernet LPI (Low Power Idle) control flags.
- HAL_ETH_ExitLPIMode(): Exit LPI (Low Power Idle) mode.

Functions

hal_status_t HAL_ETH_UpdateConfigLink ( hal_eth_handle_t * heth , const hal_eth_link_config_t * p_config ) ¶

Update the Ethernet MAC link configuration (speed and duplex mode).

This function updates the Ethernet MAC configuration register (MACCR) with the link configuration provided in p_config, specifically the link speed and duplex mode. It assumes that the Ethernet handle has already been properly initialized and is in the HAL_ETH_STATE_CONFIGURED state.

The function:

Validates input parameters (when USE_HAL_CHECK_PARAM is enabled).
Composes the link configuration value from hal_eth_link_config_t.
Updates the MACCR link-related bits.

See also

hal_eth_handle_t

See also

hal_eth_link_config_t

Note

This function only updates link configuration bits in the MACCR register (speed and duplex). It does not initiate any PHY negotiation or check link status.

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration information for the Ethernet peripheral.
p_config – [in] Pointer to a hal_eth_link_config_t structure that contains the new link configuration parameters (e.g. speed and duplex_mode).

Return values :

HAL_OK – Link configuration was successfully updated.
HAL_INVALID_PARAM – One or more input parameters are invalid (only when parameter checking is enabled via USE_HAL_CHECK_PARAM).

Pre :

heth must not be NULL.
p_config must not be NULL.
heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

void HAL_ETH_EnableARPOffload ( hal_eth_handle_t * heth ) ¶

Enable ARP offload.

This function enables the ARP offload feature in the Ethernet MAC by setting the ARP enable bit in the MAC configuration register. When ARP offload is enabled, the MAC hardware can autonomously process ARP frames according to the device-specific implementation, potentially reducing CPU involvement in ARP handling.

Note

The exact behavior of ARP offload (such as which ARP requests are answered and how IP/MAC mapping is managed) is hardware-dependent and must be checked in the device reference manual.

Parameters :: heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
Pre :: heth must not be NULL.
Pre :: heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

void HAL_ETH_DisableARPOffload ( hal_eth_handle_t * heth ) ¶

Disable ARP offload.

This function disables the ARP offload feature in the Ethernet MAC by clearing the ARP enable bit in the MAC configuration register. When ARP offload is disabled, ARP processing is fully handled by the software network stack rather than by the MAC hardware.

Parameters :: heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
Pre :: heth must not be NULL.
Pre :: heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

hal_eth_arp_offload_status_t HAL_ETH_IsEnabledARPOffload ( const hal_eth_handle_t * heth ) ¶

Check if the ETH ARP offload is enabled.

This function checks the ARP offload enable bit in the MAC configuration register and returns the current ARP offload status.

Parameters :: heth – [in] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
Return values :: hal_eth_arp_offload_status_t – Current ARP offload status (see hal_eth_arp_offload_status_t).
Pre :: heth must not be NULL.
Pre :: heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

void HAL_ETH_SetARPTargetIP ( hal_eth_handle_t * heth , uint32_t tpa ) ¶

Set the ARP target IP address.

This function programs the ARP target protocol address (TPA) used by the Ethernet MAC ARP offload logic. The tpa value is typically an IPv4 address encoded as a 32-bit value in network byte order.

Note

The exact encoding and usage of the target protocol address are hardware-dependent and must be checked in the device reference manual.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
tpa – [in] Target protocol (IP) address encoded as a 32-bit value.

Pre :

heth must not be NULL.

Pre :

heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

hal_status_t HAL_ETH_EnterPowerDownMode ( hal_eth_handle_t * heth , uint32_t pmt_ctrl ) ¶

Enter Ethernet MAC Power-Down mode with PMT configuration.

This function configures the Power Management and Timer (PMT) features of the Ethernet MAC and initiates the MAC Power-Down sequence. It can enable Remote Wakeup (RWK) and Magic Packet detection based on pmt_ctrl.

The function:

Checks that the handle is valid and in HAL_ETH_STATE_CONFIGURED.
Checks and Updates the global state from HAL_ETH_STATE_CONFIGURED to HAL_ETH_STATE_POWER_DOWN.
Programs the PMT control/status register MACPCSR with pmt_ctrl (masked by ETH_PMT_CTRL_MASK).
If any PMT trigger is enabled in pmt_ctrl:
- Enables the MAC receiver.
- Enables the PMT interrupt.
Sets the Power-Down bit in MACPCSR to start the Power-Down sequence.

See also

HAL_ETH_ExitPowerDownMode

See also

HAL_ETH_PMT_CTRL_FWD_WAKEUP_PKT

See also

HAL_ETH_PMT_CTRL_TRIG_MAGIC_PKT

See also

HAL_ETH_PMT_CTRL_TRIG_RWKUP_PKT

See also

HAL_ETH_PMT_CTRL_TRIG_GLBL_UCAST

See also

HAL_ETH_PMT_CTRL_TRIG_ALL

Note

When pmt_ctrl is 0, the MAC still enters Power-Down but no PMT wake-up source is enabled.

Note

The system clock and other peripheral clocks would need to remain enabled as required by the PMT and wake-up scheme.

Parameters :

heth – [inout] Pointer to an hal_eth_handle_t structure that contains the configuration information and state for the Ethernet peripheral. Its global_state is updated to HAL_ETH_STATE_POWER_DOWN on success.
pmt_ctrl – [in] PMT control bitmask to be written into MACPCSR (masked with ETH_PMT_CTRL_MASK). This typically includes:
- Remote wakeup filters (RWK)
- Magic Packet enable
- Other PMT-related control bits as defined by ETH_PMT_CTRL_MASK.

Return values :

HAL_OK – Power-Down sequence initiated successfully.
HAL_INVALID_PARAM – heth is NULL (only when parameter checking is enabled via USE_HAL_CHECK_PARAM).

Pre :

heth must be in HAL_ETH_STATE_CONFIGURED (checked with debug and optional runtime checks).

hal_status_t HAL_ETH_ExitPowerDownMode ( hal_eth_handle_t * heth ) ¶

Exit Ethernet MAC Power-Down mode.

This function restores the Ethernet MAC from Power-Down mode back to the configured state. It clears PMT configuration and PMT interrupt, performs dummy writes to key MAC registers as required by the hardware, and clears the Power-Down bit.

The function:

Checks that the handle is valid and in HAL_ETH_STATE_POWER_DOWN.
Checks and Updates the global state from HAL_ETH_STATE_POWER_DOWN to HAL_ETH_STATE_CONFIGURED.
Disables the PMT interrupt.
Clears PMT control bits in MACPCSR (masked by ETH_PMT_CTRL_MASK).
Performs write operations to:
- ETH_MACCR
- ETH_MACA0HR
- ETH_MACA0LR to satisfy hardware requirements when exiting Power-Down.
Clears the Power-Down bit to exit Power-Down.

See also

HAL_ETH_EnterPowerDownMode

Note

After calling this function, the MAC configuration (MACCR and MACA0 registers) would need to be revalidated or updated depending on the hardware behavior and application requirements.

Parameters :

heth – [inout] Pointer to an hal_eth_handle_t structure that contains the configuration information and state for the Ethernet peripheral. Its global_state is updated back to HAL_ETH_STATE_CONFIGURED on success.

Return values :

HAL_OK – Power-Down mode exited successfully.
HAL_INVALID_PARAM – heth is NULL (only when parameter checking is enabled via USE_HAL_CHECK_PARAM).

Pre :

heth must be in HAL_ETH_STATE_POWER_DOWN (checked with debug and optional runtime checks).

hal_status_t HAL_ETH_SetRemoteWakeUpPcktFilter ( const hal_eth_handle_t * heth , const hal_eth_rwk_filter_lut_t * p_filter_lut ) ¶

Configure the Remote Wake-Up Packet Filter LUT for Ethernet.

This function programs the Remote Wake-Up (RWK) packet filter lookup table (LUT) for the Ethernet peripheral. Each filter entry in the LUT can be configured to match specific packet patterns and control the filter logic using the following command constants:

These constants are used in the filter command field to define the behavior of each filter, such as enabling the filter, chaining filters for complex logic, inverting match logic, and specifying the address type (unicast/multicast). The maximum number of filter blocks supported by the hardware is defined by HAL_ETH_RWK_FILT_BLOCK_NUM.

The function performs the following operations:

Validates the filter LUT pointer when parameter checking is enabled.
Resets the internal RWK filter write pointer.
Writes the byte-mask words for each filter entry.
Accumulates and writes command, offset, and CRC16 fields into the dedicated RWK programming registers.

See also

hal_eth_rwk_filter_lut_t.

See also

hal_eth_rwk_pkt_filter_t.

See also

HAL_ETH_RWK_FLT_CMD_ENABLE.

See also

HAL_ETH_RWK_FLT_CMD_AND_PREVIOUS.

See also

HAL_ETH_RWK_FLT_CMD_INVERSE_MODE.

See also

HAL_ETH_RWK_FLT_CMD_MULTICAST.

See also

HAL_ETH_RWK_FILT_BLOCK_NUM.

Parameters :

heth – [in] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_filter_lut – [in] Pointer to a hal_eth_rwk_filter_lut_t structure that contains the filter entries and their command configurations. The number of filter blocks in this structure is equal to HAL_ETH_RWK_FILT_BLOCK_NUM.

Return values :

HAL_OK – Filter LUT configured successfully.
HAL_INVALID_PARAM –
- p_filter_lut is NULL when USE_HAL_CHECK_PARAM is enabled.

Pre :

heth must not be NULL.

Pre :

p_filter_lut must not be NULL.

void HAL_ETH_EnterLPIMode ( hal_eth_handle_t * heth , uint32_t lpi_ctrl ) ¶

Configure Ethernet LPI (Low Power Idle) control flags and enter LPI mode.

This function sets the LPI control flags for the Ethernet peripheral and enables Low Power Idle (LPI) mode. The lpi_ctrl parameter is a bitwise OR combination of the supported LPI control flags, which define the LPI behavior.

Supported LPI control flags are:

The function performs the following operations:

Configures the LPI control register with the specified control flags.
Enables the LPI interrupt.
Enables LPI mode in the MAC.

See also

HAL_ETH_LPI_CTRL_TX_CLK_STOP_ENABLE.

See also

HAL_ETH_LPI_CTRL_TX_AUTOMATE_ENABLE.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
lpi_ctrl – [in] Bitwise OR combination of LPI control flags that specifies the desired LPI behavior. This must be a valid combination as checked by IS_ETH_LPI_CTRL_FLAGS.

Pre :

heth must not be NULL.

Pre :

heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

Pre :

lpi_ctrl must satisfy IS_ETH_LPI_CTRL_FLAGS.

void HAL_ETH_ExitLPIMode ( hal_eth_handle_t * heth ) ¶

Exit Ethernet LPI (Low Power Idle) mode.

This function exits Low Power Idle (LPI) mode for the Ethernet MAC and restores normal operation by clearing the LPI-related configuration and disabling LPI interrupts.

The function performs the following operations:

Clears the LPI control bits that manage TX clock behavior in LPI mode.
Disables the LPI interrupt.
Disables LPI mode in the MAC.

Parameters :: heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
Pre :: heth must not be NULL.
Pre :: heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

callbacks register functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Exported_Functions_Group6

This subsection provides functions allowing the registration of the Ethernet Channel Callbacks.

HAL_ETH_RegisterChannelRxAllocateCallback(): Register Rx allocate callback for a channel.
HAL_ETH_RegisterChannelRxCptCallback(): Register Rx complete callback for a channel.
HAL_ETH_RegisterChannelTxCptCallback(): Register Tx complete callback for a channel.
HAL_ETH_RegisterDataCallback(): Register data callback.
HAL_ETH_RegisterWKUPCallback(): Register wakeup callback.
HAL_ETH_RegisterPMTCallback(): Register PMT callback.
HAL_ETH_RegisterEEECallback(): Register EEE callback.
HAL_ETH_RegisterErrorCallback(): Register error callback.
HAL_ETH_RegisterEventCallback(): Register event callback.
HAL_ETH_RegisterCacheInvalidateCallback(): Register cache invalidate callback.
HAL_ETH_RegisterCacheFlushCallback(): Register cache flush callback.
HAL_ETH_RegisterChannelRxEventCallback(): Register Rx channel events callback.
HAL_ETH_RegisterChannelTxEventCallback(): Register Tx channel events callback.

Functions

hal_status_t HAL_ETH_RegisterChannelRxAllocateCallback ( hal_eth_handle_t * heth , uint32_t channel , hal_eth_rx_allocate_cb_t p_callback ) ¶

This function registers a user-provided Rx allocate callback function for the specified Ethernet Rx channel. The callback is typically invoked by the HAL when a new buffer needs to be allocated for received data on the corresponding channel.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
channel – [in] Channel index for which the callback is to be registered, as defined by IS_ETH_CHANNEL_RX_INDEX.
p_callback – [in] Pointer to a callback function of type hal_eth_rx_allocate_cb_t to be associated with the specified Rx channel.

Return values :

HAL_OK – Callback has been successfully registered.
HAL_INVALID_PARAM –
- p_callback is NULL when USE_HAL_CHECK_PARAM is enabled.
- channel is invalid when USE_HAL_CHECK_PARAM is enabled.

Pre :

heth must not be NULL.

Pre :

p_callback must not be NULL.

Pre :

channel must be a valid Rx channel index (see IS_ETH_CHANNEL_RX_INDEX).

hal_status_t HAL_ETH_RegisterChannelRxCptCallback ( hal_eth_handle_t * heth , uint32_t channel , hal_eth_rx_complete_cb_t p_callback ) ¶

This function registers a user-provided Rx complete callback function for the specified Ethernet Rx channel. The callback is typically invoked by the HAL when a receive operation has completed on the corresponding channel.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
channel – [in] Channel index for which the callback is to be registered, as defined by IS_ETH_CHANNEL_RX_INDEX.
p_callback – [in] Pointer to a callback function of type hal_eth_rx_complete_cb_t to be associated with the specified Rx channel.

Return values :

HAL_OK – Callback has been successfully registered.
HAL_INVALID_PARAM –
- p_callback is NULL when USE_HAL_CHECK_PARAM is enabled.
- channel is invalid when USE_HAL_CHECK_PARAM is enabled.

Pre :

heth must not be NULL.

Pre :

p_callback must not be NULL.

Pre :

channel must be a valid Rx channel index (see IS_ETH_CHANNEL_RX_INDEX).

hal_status_t HAL_ETH_RegisterChannelTxCptCallback ( hal_eth_handle_t * heth , uint32_t channel , hal_eth_tx_complete_cb_t p_callback ) ¶

This function registers a user-provided Tx complete callback function for the specified Ethernet Tx channel. The callback is typically invoked by the HAL when a transmit operation has completed on the corresponding channel.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
channel – [in] Channel index for which the callback is to be registered, as defined by IS_ETH_CHANNEL_TX_INDEX.
p_callback – [in] Pointer to a callback function of type hal_eth_tx_complete_cb_t to be associated with the specified Tx channel.

Return values :

HAL_OK – Callback has been successfully registered.
HAL_INVALID_PARAM –
- p_callback is NULL when USE_HAL_CHECK_PARAM is enabled.
- channel is invalid when USE_HAL_CHECK_PARAM is enabled.

Pre :

heth must not be NULL.

Pre :

p_callback must not be NULL.

Pre :

channel must be a valid Tx channel index (see IS_ETH_CHANNEL_TX_INDEX).

hal_status_t HAL_ETH_RegisterDataCallback ( hal_eth_handle_t * heth , hal_eth_cb_t p_callback ) ¶

This function registers a user-provided data callback function for the Ethernet peripheral. The callback is typically invoked by the HAL when data-related events occur (for example, reception of new data or completion of a transmit operation), depending on the driver implementation.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_callback – [in] Pointer to a callback function of type hal_eth_cb_t to be associated with the Ethernet handle.

Return values :

HAL_OK – Callback has been successfully registered.
HAL_INVALID_PARAM –
- p_callback is NULL when USE_HAL_CHECK_PARAM is enabled.

Pre :

heth must not be NULL.

Pre :

p_callback must not be NULL.

hal_status_t HAL_ETH_RegisterWKUPCallback ( hal_eth_handle_t * heth , hal_eth_wakeup_cb_t p_callback ) ¶

This function registers a user-provided wakeup callback function for the Ethernet peripheral. The callback is typically invoked by the Ethernet wakeup event through EXTI line.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_callback – [in] Pointer to a callback function of type hal_eth_wakeup_cb_t to be associated with the Ethernet handle.

Return values :

HAL_OK – Callback has been successfully registered.
HAL_INVALID_PARAM –
- p_callback is NULL when USE_HAL_CHECK_PARAM is enabled.

Pre :

heth must not be NULL.

Pre :

p_callback must not be NULL.

hal_status_t HAL_ETH_RegisterPMTCallback ( hal_eth_handle_t * heth , hal_eth_cb_t p_callback ) ¶

This function registers a user-provided PMT callback function for the Ethernet peripheral. The callback is typically invoked by the HAL when a power management related event occurs (for example, Magic Packet or wake-up frame), depending on the driver implementation.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_callback – [in] Pointer to a callback function of type hal_eth_cb_t to be associated with the Ethernet handle for PMT events.

Return values :

HAL_OK – Callback has been successfully registered.
HAL_INVALID_PARAM –
- p_callback is NULL when USE_HAL_CHECK_PARAM is enabled.

Pre :

heth must not be NULL.

Pre :

p_callback must not be NULL.

hal_status_t HAL_ETH_RegisterEEECallback ( hal_eth_handle_t * heth , hal_eth_cb_t p_callback ) ¶

This function registers a user-provided EEE callback function for the Ethernet peripheral. The callback is typically invoked by the HAL when an EEE-related event occurs (for example, entry or exit from low power idle states), depending on the driver implementation.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_callback – [in] Pointer to a callback function of type hal_eth_cb_t to be associated with the Ethernet handle for EEE events.

Return values :

HAL_OK – Callback has been successfully registered.
HAL_INVALID_PARAM –
- p_callback is NULL when USE_HAL_CHECK_PARAM is enabled.

Pre :

heth must not be NULL.

Pre :

p_callback must not be NULL.

hal_status_t HAL_ETH_RegisterErrorCallback ( hal_eth_handle_t * heth , hal_eth_cb_t p_callback ) ¶

This function registers a user-provided error callback function for the Ethernet peripheral. The callback is typically invoked by the HAL when an error condition is detected on the Ethernet MAC, DMA, or related subsystems, depending on the driver implementation.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_callback – [in] Pointer to a callback function of type hal_eth_cb_t to be associated with the Ethernet handle for error events.

Return values :

HAL_OK – Callback has been successfully registered.
HAL_INVALID_PARAM –
- p_callback is NULL when USE_HAL_CHECK_PARAM is enabled.

Pre :

heth must not be NULL.

Pre :

p_callback must not be NULL.

hal_status_t HAL_ETH_RegisterEventCallback ( hal_eth_handle_t * heth , hal_eth_cb_t p_callback ) ¶

This function registers a user-provided generic event callback function for the Ethernet peripheral. The callback is typically invoked by the HAL when non-error, non-PMT, non-EEE events occur, depending on the driver implementation (for example, link status changes or other notifications).

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_callback – [in] Pointer to a callback function of type hal_eth_cb_t to be associated with the Ethernet handle for generic events.

Return values :

HAL_OK – Callback has been successfully registered.
HAL_INVALID_PARAM –
- p_callback is NULL when USE_HAL_CHECK_PARAM is enabled.

Pre :

heth must not be NULL.

Pre :

p_callback must not be NULL.

hal_status_t HAL_ETH_RegisterCacheInvalidateCallback ( hal_eth_handle_t * heth , hal_eth_cache_cb_t p_callback ) ¶

This function registers a user-provided cache invalidate callback function for the Ethernet peripheral. The callback is typically invoked by the HAL to invalidate data cache lines associated with internal driver memory areas allocated by the application (for DMA descriptor rings), depending on the system cache architecture and driver implementation.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_callback – [in] Pointer to a callback function of type hal_eth_cache_cb_t to be associated with the Ethernet handle for cache invalidation.

Return values :

HAL_OK – Callback has been successfully registered.
HAL_INVALID_PARAM –
- p_callback is NULL when USE_HAL_CHECK_PARAM is enabled.

Pre :

heth must not be NULL.

Pre :

p_callback must not be NULL.

hal_status_t HAL_ETH_RegisterCacheFlushCallback ( hal_eth_handle_t * heth , hal_eth_cache_cb_t p_callback ) ¶

This function registers a user-provided cache flush callback function for the Ethernet peripheral. The callback is typically invoked by the HAL to flush data cache lines associated with internal driver memory areas allocated by the application (for DMA descriptor rings), depending on the system cache architecture and driver implementation.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_callback – [in] Pointer to a callback function of type hal_eth_cache_cb_t to be associated with the Ethernet handle for cache flushing.

Return values :

HAL_OK – Callback has been successfully registered.
HAL_INVALID_PARAM –
- p_callback is NULL when USE_HAL_CHECK_PARAM is enabled.

Pre :

heth must not be NULL.

Pre :

p_callback must not be NULL.

hal_status_t HAL_ETH_RegisterChannelRxEventCallback ( hal_eth_handle_t * heth , uint32_t channel , hal_eth_channel_cb_t p_callback ) ¶

This function associates a user-provided callback p_callback with the RX channel identified by channel in the Ethernet handle heth. The callback will be invoked by the HAL when an RX channel event occurs (e.g. packet reception, error, etc. depending on implementation).

The function:

Validates heth, p_callback, and channel (with debug and optional runtime checks).
Converts the RX channel bitmask channel into a channel index.
Stores the callback pointer into heth->rx_channels[index].p_ch_event_cb.

See also

HAL_ETH_RegisterChannelTxEventCallback

Note

This function only registers the callback; the user must ensure that RX channel events are properly enabled and handled in the interrupt or polling layer that triggers the callback.

Parameters :

heth – [inout] Pointer to an hal_eth_handle_t structure that contains the configuration information and runtime state for the Ethernet peripheral.
channel – [in] RX channel identifier (bitmask) that must satisfy IS_ETH_CHANNEL_RX_INDEX. If multiple bits are set, the first valid RX channel index is used.
p_callback – [in] Pointer to a function of type hal_eth_channel_cb_t that will be called on RX channel events.

Return values :

HAL_OK – Callback successfully registered for the selected RX channel.
HAL_ERROR – RX channel index could not be derived from channel.
HAL_INVALID_PARAM –
- heth or p_callback is NULL, or
- channel is invalid (IS_ETH_CHANNEL_RX_INDEX() returns 0), and parameter checking is enabled via USE_HAL_CHECK_PARAM.

hal_status_t HAL_ETH_RegisterChannelTxEventCallback ( hal_eth_handle_t * heth , uint32_t channel , hal_eth_channel_cb_t p_callback ) ¶

This function associates a user-provided callback p_callback with the TX channel identified by channel in the Ethernet handle heth. The callback will be invoked by the HAL when a TX channel event occurs (e.g. transmit complete, error, etc., depending on implementation).

The function:

Validates heth, p_callback, and channel (with debug and optional runtime checks).
Converts the TX channel bitmask channel into a channel index.
Stores the callback pointer into heth->tx_channels[index].p_ch_event_cb.

See also

HAL_ETH_RegisterChannelRxEventCallback

Note

This function only registers the callback; the user must ensure that TX channel events are properly enabled and handled in the interrupt or polling layer that triggers the callback.

Parameters :

heth – [inout] Pointer to an hal_eth_handle_t structure that contains the configuration information and runtime state for the Ethernet peripheral.
channel – [in] TX channel identifier (bitmask) that must satisfy IS_ETH_CHANNEL_TX_INDEX. If multiple bits are set, the first valid TX channel index is used.
p_callback – [in] Pointer to a function of type hal_eth_channel_cb_t that will be called on TX channel events.

Return values :

HAL_OK – Callback successfully registered for the selected TX channel.
HAL_ERROR – TX channel index could not be derived from channel.
HAL_INVALID_PARAM –
- heth or p_callback is NULL, or
- channel is invalid (IS_ETH_CHANNEL_TX_INDEX() returns 0), and parameter checking is enabled via USE_HAL_CHECK_PARAM.

interrupts management functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Exported_Functions_Group7

This subsection provides Interrupts management functions.

HAL_ETH_WKUP_IRQHandler(): Ethernet wakeup IRQ handler.
HAL_ETH_IRQHandler(): Register Rx allocate callback for a channel.

Functions

void HAL_ETH_IRQHandler ( hal_eth_handle_t * heth ) ¶

Ethernet global interrupt handler.

This function handles all Ethernet-related interrupt sources, including MAC, DMA, MTL, PMT, EEE, data, event, wakeup, and error conditions. It reads and decodes the interrupt status of each DMA channel and MTL queue, updates internal state, clears the corresponding interrupt flags, and invokes the registered user callbacks or the weak default callbacks.

The handler performs the following main actions.

Iterates over all configured DMA channels and:
- Detects Tx and Rx data completion events and accumulates a channel data-event bitmap.
- Detects DMA/MTL channel error and status events and calls the corresponding per-channel event callbacks.
- Clears the DMA channel interrupt status flags.
If any Tx/Rx data event is detected, invokes the global data callback (registered via HAL_ETH_RegisterDataCallback or default HAL_ETH_DataCallback).
Processes MAC-level event flags (for example, link or status events) and invokes the event callback (registered via HAL_ETH_RegisterEventCallback or default HAL_ETH_EventCallback).
Checks for PMT events and calls the PMT callback (HAL_ETH_RegisterPMTCallback or HAL_ETH_PMTCallback).
Checks for EEE (Energy Efficient Ethernet) events and calls the EEE callback (HAL_ETH_RegisterEEECallback or HAL_ETH_EEECallback).
Optionally handles external wakeup (EXTI-based) events when enabled, and calls the wakeup callback (HAL_ETH_RegisterWKUPCallback or HAL_ETH_WakeUpCallback).
If a DMA error is detected, updates the global Ethernet state to HAL_ETH_STATE_FAULT, optionally stores the last error codes, and invokes the error callback (HAL_ETH_RegisterErrorCallback or HAL_ETH_ErrorCallback).

Note

This function is intended to be called from the Ethernet interrupt service routine. It must not be called directly from non-interrupt context unless the same preconditions and mutual exclusion requirements are guaranteed by the caller.

Parameters :: heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral and associated channels.
Pre :: heth must not be NULL.
Pre :: heth must have been properly initialized and configured before this handler is called (typically from the Ethernet IRQ vector).

void HAL_ETH_WKUP_IRQHandler ( const hal_eth_handle_t * heth ) ¶

Ethernet wakeup interrupt handler.

This function handles Ethernet wakeup events when the wakeup source is connected to an EXTI line. It checks the EXTI pending bits associated with the Ethernet wakeup source, clears them, and invokes the registered wakeup callback or the default HAL_ETH_WakeUpCallback.

Note

This handler is intended to be used when the Ethernet wakeup interrupt is mapped to a dedicated EXTI line, separate from the main Ethernet IRQ.

Parameters :: heth – [in] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
Pre :: heth must not be NULL.

Weak callback functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Exported_Functions_Group8

This subsection provides Weak callback functions.

HAL_ETH_DataCallback(): Ethernet Data callback.
HAL_ETH_ErrorCallback(): Ethernet Error callback.
HAL_ETH_EventCallback(): Ethernet Event callback.
HAL_ETH_PMTCallback(): Ethernet PMT callback.
HAL_ETH_EEECallback(): Ethernet EEE callback.
HAL_ETH_WakeUpCallback(): Ethernet Wakeup callback.
HAL_ETH_CacheInvalidateCallback(): Ethernet Cache Clean callback.
HAL_ETH_CacheFlushCallback(): Ethernet Cache Flush callback.
HAL_ETH_TxEventCallback(): Ethernet Tx Channel Event callback.
HAL_ETH_RxEventCallback(): Ethernet Rx Channel Event callback.

Functions

void HAL_ETH_DataCallback ( hal_eth_handle_t * heth , uint32_t channels_mask ) ¶

Ethernet Data callback (weak implementation).

This weak function is called by the HAL to notify the application that data is available or has been processed on one or more Ethernet channels. The channels are indicated by the bitmask channels_mask.

Typical usages include:

Notification that RX data is ready to be processed for one or more channels.
Notification that TX data has been processed/completed on specific channels.

The default implementation is empty and simply marks its parameters as unused. To handle such data-related events, the user application must provide a strong implementation with the same prototype and decode the channels_mask bitmask.

Note

It can be used as a central notification for data-related activity in addition to more specific per-channel callbacks.

Warning

This function is declared as __WEAK so that it can be overridden by a user-defined implementation without modifying the HAL sources.

Warning

This function must not be modified, when the callback is needed, HAL_ETH_DataCallback can be implemented in the user file.

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration and state of the Ethernet peripheral.
channels_mask – [in] Bitmask indicating the channel(s) for which a data event occurred. The meaning of each bit depends on the HAL channel definitions (e.g. RX/TX channel indices).

void HAL_ETH_ErrorCallback ( hal_eth_handle_t * heth , uint32_t errors ) ¶

Ethernet Peripheral error callback (weak implementation).

This weak function is called by the HAL when one or more Ethernet-related errors are detected. The specific error conditions are encoded in the errors bitmask (e.g. DMA errors, descriptor errors, fatal bus errors, etc., depending on the HAL error definitions).

The default implementation is empty and simply marks its parameters as unused. To handle Ethernet errors (e.g. log them, attempt recovery, notify upper layers), the user application must provide a strong implementation with the same prototype and decode the errors bitmask.

Event	Description
HAL_ETH_ERROR_NONE	No error.
HAL_ETH_ERROR_FBE	Fatal Bus Error.
HAL_ETH_ERROR_CDE	Context Descriptor Error.
HAL_ETH_ERROR_FBE_DMA_TX_RD	Bus Fault Error during read transfer by Tx DMA
HAL_ETH_ERROR_FBE_DMA_TX_WR	Bus Fault Error during write transfer by Tx DMA
HAL_ETH_ERROR_FBE_DMA_TX_AC	Bus Fault Error during descriptor access by Tx DMA
HAL_ETH_ERROR_FBE_DMA_RX_RD	Bus Fault Error during read transfer by Rx DMA
HAL_ETH_ERROR_FBE_DMA_RX_WR	Bus Fault Error during write transfer by Rx DMA
HAL_ETH_ERROR_FBE_DMA_RX_AC	Bus Fault Error during descriptor access by Rx DMA

Note

It can be used together with HAL_ETH_GetLastErrorCodes (when enabled) to retrieve and interpret accumulated error codes.

Note

The following Errors are supported:

Warning

This function is declared as __WEAK so that it can be overridden by a user-defined implementation without modifying the HAL sources.

Warning

This function must not be modified, when the callback is needed, HAL_ETH_ErrorCallback can be implemented in the user file.

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration and state of the Ethernet peripheral where the error occurred.
errors – [in] Bitmask describing the error conditions that occurred. The exact meaning of each bit depends on the Ethernet HAL error code definitions (e.g. HAL_ETH_ERROR_xxx).

void HAL_ETH_EventCallback ( hal_eth_handle_t * heth , uint32_t events ) ¶

Ethernet Peripheral event callback (weak implementation).

This weak function is called by the HAL to notify the application about global Ethernet events represented by the bitmask events.

The default implementation is empty and simply marks its parameters as unused. To react to these global Ethernet events, the user application must provide a strong implementation with the same prototype and decode the events bitmask.

Event	Description
HAL_ETH_EVENT_MAC_RWT	Receive Watchdog Timeout Event.
HAL_ETH_EVENT_MAC_EXCOL	Excessive Collisions Event.
HAL_ETH_EVENT_MAC_LCOL	Late Collision Event.
HAL_ETH_EVENT_MAC_EXDEF	Excessive Deferral Event.
HAL_ETH_EVENT_MAC_LCARR	Loss of Carrier Event.
HAL_ETH_EVENT_MAC_NCARR	No Carrier Event.
HAL_ETH_EVENT_MAC_TJT	Transmit Jabber Timeout Event.

Note

The following Ethernet Peripheral Events are supported:

Warning

This function is declared as __WEAK so that it can be overridden by a user-defined implementation without modifying the HAL sources.

Warning

This function must not be modified, when the callback is needed, HAL_ETH_EventCallback can be implemented in the user file.

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration and state of the Ethernet peripheral.
events – [in] Bitmask of Ethernet events that occurred. The exact meaning of each bit is defined by the Ethernet HAL event definitions.

void HAL_ETH_PMTCallback ( hal_eth_handle_t * heth , uint32_t wake_up_event ) ¶

Ethernet Power Management and Timer (PMT) wake-up event callback (weak implementation).

This weak function is called by the HAL to notify the application that a PMT-related wake-up event has occurred on the Ethernet MAC layer. Typical wake-up sources include:

Magic Packet reception
Remote wake-up frame match
Other PMT triggers, depending on the hardware configuration.

The default implementation is empty and simply marks its parameters as unused. To handle PMT wake-up events (e.g. restore configuration, restart traffic, notify upper layers), the user application must provide a strong implementation with the same prototype and react to the wake_up_event bitmask.

Event	Description
HAL_ETH_EVENT_PMT_MAGIC_PACKET	Magic Packet Received.
HAL_ETH_EVENT_PMT_RWK_PACKET	Remote wake-up Packet Received.

Note

It is typically used together with power management APIs such as HAL_ETH_EnterPowerDownMode and HAL_ETH_ExitPowerDownMode.

Note

The following Ethernet Peripheral PMT Events are supported:

Warning

This function is declared as __WEAK so that it can be overridden by a user-defined implementation without modifying the HAL sources.

Warning

This function must not be modified, when the callback is needed, HAL_ETH_PMTCallback can be implemented in the user file.

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration and state of the Ethernet peripheral that triggered the wake-up.
wake_up_event – [in] Bitmask describing the PMT wake-up event(s) that occurred. The exact meaning of each bit depends on the Ethernet HAL PMT event definitions.

void HAL_ETH_EEECallback ( hal_eth_handle_t * heth , uint32_t lpi_event ) ¶

Ethernet Energy Efficient Ethernet (EEE) / LPI event callback (weak implementation).

This weak function is called by the HAL to notify the application about Energy Efficient Ethernet (EEE) / Low Power Idle (LPI) related events. The specific event is encoded in lpi_event as a bitmask (for example, LPI entry, LPI exit, error conditions, etc., depending on the HAL definitions).

The default implementation is empty and simply marks its parameters as unused. To handle EEE/LPI events (e.g. update power statistics, adapt traffic scheduling, logging), the user application must provide a strong implementation with the same prototype.

Event	Description
HAL_ETH_EVENT_LPI_PLS_DOWN	PHY Link Status is Down.
HAL_ETH_EVENT_LPI_PLS_UP	PHY Link Status is Up.
HAL_ETH_EVENT_LPI_TX_LPI_ST	Transmit LPI State Active.
HAL_ETH_EVENT_LPI_RX_LPI_ST	Receive LPI State Active.
HAL_ETH_EVENT_LPI_TX_LPI_EN	Transmit LPI State Entry performed.
HAL_ETH_EVENT_LPI_RX_LPI_EN	Receive LPI State Entry performed.
HAL_ETH_EVENT_LPI_TX_LPI_EX	Transmit LPI State Entry performed.
HAL_ETH_EVENT_LPI_RX_LPI_EX	Receive LPI State Entry performed.

Note

It is typically used when EEE support is enabled in the MAC/PHY and LPI events are monitored by the application together with low power interface APIs such as HAL_ETH_EnterLPIMode and HAL_ETH_ExitLPIMode.

Note

The following Peripheral EEE/LPI Events are supported:

Warning

This function is declared as __WEAK so that it can be overridden by a user-defined implementation without modifying the HAL sources.

Warning

This function must not be modified, when the callback is needed, HAL_ETH_EEECallback can be implemented in the user file.

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration and state of the Ethernet peripheral.
lpi_event – [in] Bitmask describing the EEE / LPI event that occurred. The exact meaning of each bit depends on the Ethernet HAL EEE/LPI event definitions.

void HAL_ETH_WakeUpCallback ( const hal_eth_handle_t * heth ) ¶

Ethernet wake-up event callback (weak implementation).

This weak function is called by the HAL when the Ethernet MAC/PHY causes a wake-up event, typically after exiting a power-down or low-power mode due to a PMT trigger (e.g. Magic Packet, Remote Wakeup frame).

The default implementation is empty and simply marks heth as unused. To react to Ethernet wake-up events (e.g. reconfigure the interface, restart transmissions, notify upper layers), the user application must provide a strong implementation with the same prototype.

Note

It is typically used in conjunction with power management APIs such as HAL_ETH_EnterPowerDownMode and HAL_ETH_ExitPowerDownMode.

Warning

This function is declared as __WEAK so that it can be overridden by a user-defined implementation without modifying the HAL sources.

Warning

This function must not be modified, when the callback is needed, HAL_ETH_WakeUpCallback can be implemented in the user file.

Parameters :: heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration and state of the Ethernet peripheral that triggered the wake-up.

void HAL_ETH_CacheInvalidateCallback ( hal_eth_handle_t * heth , uint32_t channel , void * p_addr , uint32_t size ) ¶

Cache invalidate callback for Ethernet buffer regions (weak implementation).

This weak function is intended to be overridden by the user application when cache maintenance is required for the memory used by theEthernet peripheral. It is typically called by the HAL before accessing data in memory regions that can be cached, so that the CPU view of memory remains coherent with what DMA has written or will read.

The default implementation is empty and simply marks all parameters as unused. If cache maintenance is needed on the target system, the user must provide a strong implementation with the same prototype to perform the appropriate cache invalidate operation on the buffer range [ p_addr, p_addr + size).

See also

HAL_ETH_CacheFlushCallback

Note

On systems without data cache, this callback can remain unimplemented.

Warning

This function is declared as __WEAK so that it can be overridden by a user-defined implementation without modifying the HAL sources.

Warning

This function must not be modified, when the callback is needed, HAL_ETH_CacheInvalidateCallback can be implemented in the user file.

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration and state of the Ethernet peripheral.
channel – [in] Ethernet channel identifier associated with the buffer. This can be used by the user implementation to distinguish per-channel handling if needed.
p_addr – [in] Pointer to the start of the memory region (buffer) to be invalidated from the CPU data cache.
size – [in] Size in bytes of the memory region to be invalidated.

void HAL_ETH_CacheFlushCallback ( hal_eth_handle_t * heth , uint32_t channel , void * p_addr , uint32_t size ) ¶

Cache flush (clean) callback for Ethernet buffer regions (weak implementation).

This weak function is intended to be overridden by the user application when cache maintenance is required for Ethernet RX/TX buffers before DMA accesses. It is typically called by the HAL to ensure that any modified data in the CPU data cache is written back to memory so that the Ethernet DMA sees the latest data.

The default implementation is empty and simply marks all parameters as unused. If cache maintenance is needed on the target system, the user must provide a strong implementation with the same prototype to perform the appropriate cache clean/flush operation on the buffer range [ p_addr, p_addr + size).

See also

HAL_ETH_CacheInvalidateCallback

Note

On systems without data cache, this callback can remain unimplemented.

Warning

This function is declared as __WEAK so that it can be overridden by a user-defined implementation without modifying the HAL sources.

Warning

This function must not be modified, when the callback is needed, HAL_ETH_CacheFlushCallback can be implemented in the user file.

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration and state of the Ethernet peripheral.
channel – [in] Ethernet channel identifier associated with the buffer. This can be used by the user implementation to distinguish per-channel handling if needed.
p_addr – [in] Pointer to the start of the memory region (buffer) to be flushed (cleaned) from the CPU data cache to main memory.
size – [in] Size in bytes of the memory region to be flushed.

void HAL_ETH_TxEventCallback ( hal_eth_handle_t * heth , uint32_t channel , uint32_t events ) ¶

Ethernet Transmit (TX) event callback (weak implementation).

This weak function is invoked by the HAL to notify the application about TX-related events on a given Ethernet channel. Typical events include transmit complete, transmit errors, or other channel-specific conditions, encoded in events as a bitmask.

The default implementation is empty and simply marks all parameters as unused. To handle TX events, the user application must provide a strong implementation with the same prototype and perform the desired processing based on the channel and events values.

Event	Description
HAL_ETH_CH_EVENT_DMA_RBU	Receive Buffer Unavailable.
HAL_ETH_CH_EVENT_DMA_TBU	Transmit Buffer Unavailable.
HAL_ETH_CH_EVENT_DMA_RWT	Receive Watchdog Timeout.
HAL_ETH_CH_EVENT_MTL_RX_OF	MTL Receive Queue Overflow.
HAL_ETH_CH_EVENT_MTL_TX_OF	MTL Transmit Queue Underflow.

See also

hal_eth_handle_t

See also

ETH channel event codes

See also

HAL_ETH_RegisterChannelTxEventCallback

See also

hal_eth_channel_cb_t

Note

The HAL can also provide per-channel callbacks (registered via HAL_ETH_RegisterChannelTxEventCallback) which can be used instead of this global callback.

Note

The following events are supported:

Warning

This function is declared as __WEAK so that it can be overridden by a user-defined implementation without modifying the HAL sources.

Warning

This function must not be modified, when the callback is needed, HAL_ETH_TxEventCallback can be implemented in the user file.

Note

The callback function can be invoked in handler mode; therefore, it must execute quickly and must not perform any blocking operations.
If additional processing is required, it is recommended to defer such operations to a separate task or thread.

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration and state of the Ethernet peripheral.
channel – [in] TX channel identifier on which the event occurred.
events – [in] Bitmask of TX events that occurred on the specified channel. The exact meaning of each bit depends on the Ethernet HAL event definitions (e.g. TX complete, TX error, etc.).

void HAL_ETH_RxEventCallback ( hal_eth_handle_t * heth , uint32_t channel , uint32_t events ) ¶

Ethernet reception (RX) event callback (weak implementation).

This weak function is invoked by the HAL to notify the application about RX-related events on a given Ethernet channel. Typical events include reception complete, reception errors, or other channel-specific conditions, encoded in events as a bitmask.

The default implementation is empty and simply marks all parameters as unused. To handle RX events, the user application must provide a strong implementation with the same prototype and perform the desired processing based on the channel and events values.

Event	Description
HAL_ETH_CH_EVENT_DMA_RBU	Receive Buffer Unavailable.
HAL_ETH_CH_EVENT_DMA_TBU	Transmit Buffer Unavailable.
HAL_ETH_CH_EVENT_DMA_RWT	Receive Watchdog Timeout.
HAL_ETH_CH_EVENT_MTL_RX_OF	MTL Receive Queue Overflow.
HAL_ETH_CH_EVENT_MTL_TX_OF	MTL Transmit Queue Underflow.

See also

hal_eth_handle_t

See also

ETH channel event codes

See also

HAL_ETH_RegisterChannelRxEventCallback

See also

hal_eth_channel_cb_t

Note

The HAL can also provide per-channel callbacks (registered via HAL_ETH_RegisterChannelRxEventCallback) which can be used instead of this global callback.

Note

The following events are supported:

Warning

This function is declared as __WEAK so that it can be overridden by a user-defined implementation without modifying the HAL sources.

Warning

This function must not be modified, when the callback is needed, HAL_ETH_RxEventCallback can be implemented in the user file.

Note

The callback function can be invoked in handler mode; therefore, it must execute quickly and must not perform any blocking operations.
If additional processing is required, it is recommended to defer such operations to a separate task or thread.

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration and state of the Ethernet peripheral.
channel – [in] RX channel identifier on which the event occurred.
events – [in] Bitmask of RX events that occurred on the specified channel. The exact meaning of each bit depends on the Ethernet HAL event definitions (e.g. RX complete, RX error, etc.).

Process and I/O operations functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Exported_Functions_Group9

Functions

hal_status_t HAL_ETH_ExecDataHandler ( hal_eth_handle_t * heth , uint32_t input_channel_mask , uint32_t * p_output_channel_mask ) ¶

Execute Ethernet TX/RX data handlers for the specified channels.

This function processes pending TX and/or RX descriptors for the channels selected by input_channel_mask. It walks through each selected channel, locks it, inspects its descriptor list, calls user callbacks for completed packets, updates descriptor state and counters, and then unlocks the channel. Channels that could not be processed (locked or callback failure) are reported via p_output_channel_mask.

The data execution handler starts by scanning all requested Tx channels in the input_channel_mask list, then proceeds with all Rx channels in the list.

TX path:

For each TX channel bit set in input_channel_mask:
- Ensure the channel state is HAL_ETH_CHANNEL_STATE_ACTIVE or HAL_ETH_CHANNEL_STATE_SUSPENDED.
- Lock the TX channel.
  - If lock fails, set the corresponding bit in *p_output_channel_mask and continue with the next channel.
- Iterate the used TX descriptors (from heth->tx_channels[ch].tx_desc_list.built_desc_id):
  - Invalidate cache for the descriptor.
  - If descriptor is still owned by DMA (ETH_DMA_TX_DESC_RF_OWN): stop processing this channel.
  - If no packet is attached (p_pkt_addr == NULL):
    - Treat it as a context descriptor and reset it.
  - Otherwise:
    - Build a hal_eth_tx_cb_pkt_data_t structure with:
      - Status bits (FD/LD).
      - Error bits (IH, ED, EC, LC, NC, LOC, PC, JT).
      - Application context pointer (p_app_data).
    - Call the TX complete callback p_tx_complete_cb(heth, channel_id, p_pkt_addr, tx_cb_pkt_data).
      - If it returns not HAL_OK, set the channel bit in *p_output_channel_mask, keep the descriptor, and stop processing this channel.
    - If callback succeeds, reset the descriptor.
  - Flush cache for the descriptor.
  - Move to the next descriptor and decrement buff_in_use.
- Store updated descriptor index and used count in the handle.
- Unlock the TX channel.

RX path:

For each RX channel bit set in input_channel_mask:
- Ensure the channel state is HAL_ETH_CHANNEL_STATE_ACTIVE or HAL_ETH_CHANNEL_STATE_SUSPENDED.
- Lock the RX channel.
  - If lock fails, set the channel bit in *p_output_channel_mask and continue with the next channel.
- Iterate the used RX descriptors (from heth->rx_channels[ch].rx_desc_list.built_desc_id):
  - Invalidate cache for the descriptor.
  - If descriptor is still owned by DMA (ETH_DMA_RX_DESC_WBF_OWN): stop processing this channel.
  - If descriptor is a context descriptor (ETH_DMA_RX_DESC_WBF_CTXT set):
    - Clear its fields (backup address & context).
  - Otherwise:
    - Build a hal_eth_rx_cb_pkt_data_t structure:
      - Read packet length from ETH_DMA_RX_DESC_WBF_PL.
      - Set status bits (FD/LD).
      - If LD is set:
        
        Copy additional status bits (IPCB, IPv4, IPv6, ARPNR, VLAN) from desc1/desc2/desc3.
        
        If VLAN present:
        
        Copy VLAN tag value from desc0 into vlan_tag_ids.
      - Set error bits using desc1/desc3 (IPH, IPC, DB, REC, OFL, RWT, GP, CRC).
      - Set application context from p_app_data.
    - Call the RX complete callback
      p_rx_complete_cb(heth, channel_id, p_pkt_addr, rec_pkt_size,
      rx_pkt_data).
      - If it returns not HAL_OK, set the channel bit in *p_output_channel_mask, keep the descriptor, and stop processing this channel.
    - If callback succeeds, reset the descriptor.
  - Flush cache for the descriptor.
  - Move to the next descriptor and decrement buff_in_use.
- Store updated descriptor index and used count in the handle.
- Replenish RX descriptors.
- Unlock the RX channel.

Note

Cache maintenance is performed either via user-registered callbacks ( p_cache_invalidate_cb, p_cache_flush_cb) when USE_HAL_ETH_REGISTER_CALLBACKS is enabled, or via the weak default implementations HAL_ETH_CacheInvalidateCallback and HAL_ETH_CacheFlushCallback otherwise.

Note

This function does not start or stop channels; it only processes descriptors for channels that are already active or suspended.

Note

This function is not intended to be called from a handler execution mode (interrupt context). In a bare-metal integration, the application must implement a deferred call mechanism so that it is invoked later from thread mode (process context).

Parameters :

heth – [inout] Pointer to an hal_eth_handle_t structure containing the configuration and runtime state for the Ethernet peripheral. Its tx_channels[] and rx_channels[] descriptor lists are updated by this function.
input_channel_mask – [in] Bitmask indicating which channels to process. It can contain:
- TX channel bits (subset of HAL_ETH_TX_CHANNEL_ALL).
- RX channel bits (subset of HAL_ETH_RX_CHANNEL_ALL). Both TX and RX handling are performed if both groups are present.
p_output_channel_mask – [inout] Pointer to a bitmask used to report channels that could not be fully processed. On input, the value can contain an initial mask (typically 0). On output, bits are set for channels where:
- The channel is locked (could not be acquired).
- The user TX/RX complete callback returned an error (descriptor kept for next execution).

Return values :

HAL_OK – Data handler executed; channels requiring further processing are indicated via *p_output_channel_mask.
HAL_INVALID_PARAM – heth or p_output_channel_mask is NULL (only when parameter checking is enabled via USE_HAL_CHECK_PARAM).

Pre :

heth must not be NULL.
p_output_channel_mask must not be NULL.
heth->global_state must be HAL_ETH_STATE_CONFIGURED (checked with debug and optional runtime checks).

hal_status_t HAL_ETH_RequestTx ( hal_eth_handle_t * heth , uint32_t channel , hal_eth_buffer_t * p_buff_array , uint32_t buf_count , hal_eth_tx_pkt_config_t * p_tx_conf ) ¶

Request transmission of a packet on the specified TX channel.

This function prepares and queues one Ethernet packet for transmission on a given TX channel by configuring the corresponding DMA descriptors. The packet is described by an array of buffers p_buff_array and a TX configuration structure p_tx_conf.

The function:

Validates parameters and channel index.
Translates the channel bitmask into a TX channel index.
Checks that the TX channel state is HAL_ETH_CHANNEL_STATE_ACTIVE or HAL_ETH_CHANNEL_STATE_SUSPENDED.
Locks the TX channel; if the channel is already locked, it returns HAL_BUSY.
Prepare DMA TX descriptors for the specified buffers and configuration.
Unlocks the TX channel and returns the status.

See also

HAL_ETH_ExecDataHandler

Note

This function only prepares the DMA descriptors; the current start of transmission depends on the number of already queued packets which are still pending for execution by the Ethernet DMA engine.

Parameters :

heth – [inout] Pointer to an hal_eth_handle_t structure that contains the configuration and runtime state of the Ethernet peripheral.
channel – [in] TX channel identifier (bitmask), must satisfy IS_ETH_CHANNEL_TX_INDEX. If multiple bits are set, only the first matching TX channel index is used.
p_buff_array – [in] Pointer to an array of hal_eth_buffer_t structures describing the buffer(s) that make up the packet to transmit (address and size).
buf_count – [in] Number of elements in p_buff_array.
p_tx_conf – [in] Pointer to a hal_eth_tx_pkt_config_t structure that contains per-packet TX configuration (e.g. checksums, VLAN tagging, etc.).

Return values :

HAL_OK – The packet was successfully queued for transmission via DMA.
HAL_BUSY –
- The specified TX channel is currently locked and cannot accept a new transmission request.
- Not enough free descriptors available to queue the packet.
HAL_INVALID_PARAM –
- heth, p_buff_array, or p_tx_conf is NULL, or
- channel is invalid (IS_ETH_CHANNEL_TX_INDEX() returns 0), and parameter checking is enabled via USE_HAL_CHECK_PARAM.

Pre :

heth must have been initialized and configured (HAL_ETH_Init + HAL_ETH_SetConfig).
heth->global_state must be HAL_ETH_STATE_CONFIGURED (checked with debug and optional runtime checks).
The TX channel must be in HAL_ETH_CHANNEL_STATE_ACTIVE or HAL_ETH_CHANNEL_STATE_SUSPENDED.

hal_status_t HAL_ETH_StartChannel ( hal_eth_handle_t * heth , uint32_t channel , uint32_t * p_desc_mem , uint32_t desc_size_byte ) ¶

Start an Ethernet TX or RX channel.

This function initializes the descriptor list and starts either a TX or RX channel, depending on the channel identifier. It configures DMA and MTL for the selected channel, enables the required DMA/MAC interrupts, and starts the corresponding DMA and MAC data path.

The descriptor memory p_desc_mem must be aligned on the bus data width (ETH_BUS_DATA_WIDTH_BYTE) and large enough to hold all descriptors for the selected channel.

TX channel start:

Derive TX channel index from channel.
Check channel state is HAL_ETH_CHANNEL_STATE_CONFIGURED.
Check mandatory TX callback p_tx_complete_cb is registered.
Move channel state to HAL_ETH_CHANNEL_STATE_ACTIVE using ETH_STATES_CHECK_UPDATE.
Initialize the TX descriptor list.
Enable TX DMA interrupts (NIE, AIE, CDEE, FBEE, TIE).
Flush TX FIFO, start DMA TX, clear TX stopped status, enable MAC TX.

RX channel start:

Derive RX channel index from channel.
Check channel state is HAL_ETH_CHANNEL_STATE_CONFIGURED.
Check mandatory RX callbacks p_rx_complete_cb and p_rx_allocate_cb are registered.
Move channel state to HAL_ETH_CHANNEL_STATE_ACTIVE using ETH_STATES_CHECK_UPDATE.
Initialize the RX descriptor list.
Enable RX DMA interrupts (NIE, AIE, CDEE, FBEE, RIE, RBUE).
Start DMA RX and enable MAC RX.

Note

This function does not allocate data buffers; it only initializes descriptor lists and starts the hardware for the given channel.

Note

For RX channels, the p_rx_allocate_cb callback is expected to allocate and attach buffers to the RX descriptors during operation.

Parameters :

heth – [inout] Pointer to an hal_eth_handle_t structure that contains the configuration information and runtime state for the Ethernet peripheral.
channel – [in] Channel identifier that must satisfy IS_ETH_CHANNEL_INDEX. If it matches any bit in HAL_ETH_TX_CHANNEL_ALL, a TX channel is started; otherwise an RX channel is started.
p_desc_mem – [in] Pointer to the descriptor memory area for the selected channel. Must be aligned on ETH_BUS_DATA_WIDTH_BYTE.
desc_size_byte – [in] Size in bytes of the descriptor memory region pointed to by p_desc_mem.

Return values :

HAL_OK – The channel was successfully started.
HAL_INVALID_PARAM –
- heth or p_desc_mem is NULL, or
- channel is invalid (IS_ETH_CHANNEL_INDEX() returns 0), or
- p_desc_mem is not aligned to ETH_BUS_DATA_WIDTH_BYTE, or
- Mandatory p_tx_complete_cb callback for the selected channel is not set.

Pre :

heth must have been initialized and configured (HAL_ETH_Init + HAL_ETH_SetConfig).
heth->global_state must be HAL_ETH_STATE_CONFIGURED (checked with debug and optional runtime checks).
The selected channel must be in HAL_ETH_CHANNEL_STATE_CONFIGURED.

hal_status_t HAL_ETH_StopChannel ( hal_eth_handle_t * heth , uint32_t channel ) ¶

Stop an Ethernet TX or RX channel.

This function stops either a TX or RX channel, depending on the channel identifier. It updates the channel state, acquires the channel lock, calls the appropriate low-level stop routine, and then releases the lock.

TX channel stop:

Determine TX channel index from channel.
Check channel state is HAL_ETH_CHANNEL_STATE_ACTIVE.
Move channel state to HAL_ETH_CHANNEL_STATE_CONFIGURED using ETH_STATES_CHECK_UPDATE.
Lock the TX channel;
- On failure, restore state to HAL_ETH_CHANNEL_STATE_ACTIVE and return HAL_BUSY.
Stop DMA/MTL/MAC activity on this TX channel.
Unlock the channel.

RX channel stop:

Determine RX channel index from channel.
Check channel state is HAL_ETH_CHANNEL_STATE_ACTIVE.
Move channel state to HAL_ETH_CHANNEL_STATE_CONFIGURED using ETH_STATES_CHECK_UPDATE.
Lock the RX channel;
- On failure, restore state to HAL_ETH_CHANNEL_STATE_ACTIVE and return HAL_BUSY.
Stop DMA/MTL/MAC activity on this RX channel.
Unlock the channel.

See also

HAL_ETH_StartChannel

Note

This function does not de-initialize the descriptor lists; it only stops the DMA/MAC activity for the specified channel. Descriptors can be reused after restarting the channel.

Parameters :

heth – [inout] Pointer to an hal_eth_handle_t structure that contains the configuration information and runtime state for the Ethernet peripheral.
channel – [in] Channel identifier (bitmask) that must satisfy IS_ETH_CHANNEL_INDEX. If it intersects HAL_ETH_TX_CHANNEL_ALL, a TX channel is stopped; otherwise an RX channel is stopped.

Return values :

HAL_OK – The selected channel was successfully stopped.
HAL_BUSY – The selected channel could not be locked for stopping; its state is restored to HAL_ETH_CHANNEL_STATE_ACTIVE.
HAL_ERROR – Hardware error occurred while stopping the channel.
HAL_INVALID_PARAM –
- heth is NULL, or
- channel is invalid (IS_ETH_CHANNEL_INDEX() returns 0), and parameter checking is enabled via USE_HAL_CHECK_PARAM.

Pre :

The selected channel must be in HAL_ETH_CHANNEL_STATE_ACTIVE.
heth must have been initialized and configured.

hal_status_t HAL_ETH_SuspendChannel ( hal_eth_handle_t * heth , uint32_t channel ) ¶

Suspend an Ethernet TX or RX channel.

This function suspends activity on either a TX or RX channel, depending on the channel bitmask. For TX channels, it stops the DMA transmission and waits for the queue to drain; for RX channels, it stops the DMA reception. The channel state is updated from HAL_ETH_CHANNEL_STATE_ACTIVE to HAL_ETH_CHANNEL_STATE_SUSPENDED.

TX channel suspend:

Determine TX channel index from channel.
Check channel state is HAL_ETH_CHANNEL_STATE_ACTIVE.
Update channel state to HAL_ETH_CHANNEL_STATE_SUSPENDED using ETH_STATES_CHECK_UPDATE.
Disable TX DMA transmission (clear TXCR_ST).
Wait for the MTL TX queue to finish the current transfer by polling MTLTXQXDR until the queue status bits (e.g. TXQSTS) are cleared or ETH_TX_DMA_STOP_TIMEOUT elapses.

RX channel suspend:

Determine RX channel index from channel.
Check channel state is HAL_ETH_CHANNEL_STATE_ACTIVE.
Update channel state to HAL_ETH_CHANNEL_STATE_SUSPENDED using ETH_STATES_CHECK_UPDATE.
Disable RX DMA reception (clear RXCR_SR).

See also

HAL_ETH_StartChannel

See also

HAL_ETH_StopChannel

Note

This API only suspends the DMA path; descriptors and channel configuration are preserved and can be resumed later by a dedicated resume/start API.

Parameters :

heth – [inout] Pointer to an hal_eth_handle_t structure that contains the configuration information and runtime state for the Ethernet peripheral.
channel – [in] Channel identifier (bitmask) that must satisfy IS_ETH_CHANNEL_INDEX. If it intersects HAL_ETH_TX_CHANNEL_ALL, a TX channel is suspended; otherwise an RX channel is suspended.

Return values :

HAL_OK – The selected channel was successfully suspended.
HAL_ERROR –
- Timeout occurred while waiting for the TX queue to drain.
HAL_INVALID_PARAM –
- heth is NULL, or
- channel is invalid (IS_ETH_CHANNEL_INDEX() returns 0), and parameter checking is enabled via USE_HAL_CHECK_PARAM.

Pre :

The selected channel must be in HAL_ETH_CHANNEL_STATE_ACTIVE.
heth must have been initialized and configured.

hal_status_t HAL_ETH_ResumeChannel ( hal_eth_handle_t * heth , uint32_t channel ) ¶

Resume a previously suspended Ethernet TX or RX channel.

This function resumes DMA activity on either a TX or RX channel, depending on the channel bitmask. It updates the channel state from HAL_ETH_CHANNEL_STATE_SUSPENDED back to HAL_ETH_CHANNEL_STATE_ACTIVE and reenables the corresponding DMA control bit.

TX channel resume:

Determine TX channel index from channel.
Check channel state is HAL_ETH_CHANNEL_STATE_SUSPENDED.
Update channel state to HAL_ETH_CHANNEL_STATE_ACTIVE using ETH_STATES_CHECK_UPDATE.
Enable TX DMA transmission (set TXCR_ST).

RX channel resume:

Determine RX channel index from channel.
Check channel state is HAL_ETH_CHANNEL_STATE_SUSPENDED.
Update channel state to HAL_ETH_CHANNEL_STATE_ACTIVE using ETH_STATES_CHECK_UPDATE.
Enable RX DMA reception (set RXCR_SR).

See also

HAL_ETH_SuspendChannel

See also

HAL_ETH_StartChannel

Note

This function only resumes DMA activity; descriptor lists and other channel settings are assumed to be valid from prior configuration.

Parameters :

heth – [inout] Pointer to an hal_eth_handle_t structure that contains the configuration information and runtime state for the Ethernet peripheral.
channel – [in] Channel identifier (bitmask) that must satisfy IS_ETH_CHANNEL_INDEX. If it intersects HAL_ETH_TX_CHANNEL_ALL, a TX channel is resumed; otherwise an RX channel is resumed.

Return values :

HAL_OK – The selected channel was successfully resumed.
HAL_ERROR – Channel index could not be derived from channel.
HAL_INVALID_PARAM –
- heth is NULL, or
- channel is invalid (IS_ETH_CHANNEL_INDEX() returns 0), and parameter checking is enabled via USE_HAL_CHECK_PARAM.

Pre :

The selected channel must be in HAL_ETH_CHANNEL_STATE_SUSPENDED.
heth must have been initialized, configured, and the channel previously started and suspended.

uint32_t HAL_ETH_GetChannelBufferInUseCount ( const hal_eth_handle_t * heth , uint32_t channel ) ¶

Get the number of buffers in use (owned by the hardware) for a channel.

The returned counter (TX/RX buff_in_use) is maintained by the driver and is updated when TX buffers are queued (via HAL_ETH_RequestTx), and when RX/TX completions are processed (via HAL_ETH_ExecDataHandler.

This function returns the current number of buffers in use (owned by the hardware) for the specified Ethernet channel (Tx or Rx). The channel type is inferred from channel using the HAL_ETH_TX_CHANNEL_ALL mask.

Parameters :

heth – [in] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
channel – [in] Channel index, as defined by IS_ETH_CHANNEL_INDEX. The function automatically distinguishes between Tx and Rx channels using HAL_ETH_TX_CHANNEL_ALL.

Return values :

Number – of buffers currently in use (owned by the hardware) for the specified channel.

Pre :

heth must not be NULL.

Pre :

p_buf_cnt must not be NULL.

Pre :

channel must be a valid channel index (see IS_ETH_CHANNEL_INDEX).

Pre :

heth->global_state must be equal to HAL_ETH_STATE_CONFIGURED.

Pre :

The corresponding channel state must be HAL_ETH_CHANNEL_STATE_CONFIGURED or HAL_ETH_CHANNEL_STATE_ACTIVE.

Multi-Queue functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Exported_Functions_Group10

This subsection provides the Ethernet Multi-Queue Functions.

HAL_ETH_GetRxDMAChNumber(): Get the number of Rx DMA channels.

Functions

uint32_t HAL_ETH_GetRxDMAChNumber ( const hal_eth_handle_t * heth ) ¶

Get the number of Rx DMA channels.

This function returns the maximum number of Rx DMA channels supported by the Ethernet HAL configuration, as defined by USE_HAL_ETH_MAX_RX_CH_NB.

Parameters :: heth – [in] Pointer to a hal_eth_handle_t structure. This parameter is currently unused.
Return values :: Number – of Rx DMA channels.

uint32_t HAL_ETH_GetTxDMAChNumber ( const hal_eth_handle_t * heth ) ¶

Get the number of Tx DMA channels.

This function returns the maximum number of Tx DMA channels supported by the Ethernet HAL configuration, as defined by USE_HAL_ETH_MAX_TX_CH_NB.

Parameters :: heth – [in] Pointer to a hal_eth_handle_t structure. This parameter is currently unused.
Return values :: Number – of Tx DMA channels.

uint32_t HAL_ETH_GetRxMTLQNumber ( const hal_eth_handle_t * heth ) ¶

Get the number of Rx MTL queues.

This function returns the maximum number of Rx MTL queues supported by the Ethernet HAL configuration. In this implementation, the number of Rx MTL queues is equal to USE_HAL_ETH_MAX_RX_CH_NB.

Parameters :: heth – [in] Pointer to a hal_eth_handle_t structure. This parameter is currently unused.
Return values :: Number – of Rx MTL queues.

uint32_t HAL_ETH_GetTxMTLQNumber ( const hal_eth_handle_t * heth ) ¶

Get the number of Tx MTL queues.

This function returns the maximum number of Tx MTL queues supported by the Ethernet HAL configuration. In this implementation, the number of Tx MTL queues is equal to USE_HAL_ETH_MAX_TX_CH_NB.

Parameters :: heth – [in] Pointer to a hal_eth_handle_t structure. This parameter is currently unused.
Return values :: Number – of Tx MTL queues.

state and error functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Exported_Functions_Group11

This subsection provides the Ethernet Peripheral and Channel State and Error Functions.

HAL_ETH_GetState(): Get the global state of the Ethernet peripheral.
HAL_ETH_GetChannelState(): Get the state of a channel.
HAL_ETH_GetLastErrorCodes(): Get the last error codes.

Functions

hal_eth_state_t HAL_ETH_GetState ( const hal_eth_handle_t * heth ) ¶

Return the global state of the Ethernet HAL driver.

This function retrieves the current global state of the Ethernet HAL associated with the given handle heth. The state reflects the overall lifecycle of the peripheral (e.g. reset, initialized, ready, busy, error).

Note

This function does not perform any synchronization; it simply returns the current value of heth->global_state.

Parameters :

heth – [in] Pointer to a constant hal_eth_handle_t structure that holds the Ethernet configuration and runtime state.

Return values :

hal_eth_state_t – The current global Ethernet state, typically one of:
- HAL_ETH_STATE_RESET
- HAL_ETH_STATE_INIT
- HAL_ETH_STATE_CONFIGURED
- HAL_ETH_STATE_POWER_DOWN
- HAL_ETH_STATE_FAULT (Exact values depend on the hal_eth_state_t enumeration.)
HAL_ETH_STATE_RESET – Returned if heth is NULL and parameter checking is enabled (USE_HAL_CHECK_PARAM == 1).

hal_eth_channel_state_t HAL_ETH_GetChannelState ( const hal_eth_handle_t * heth , uint32_t channel ) ¶

Get the current state of an Ethernet TX or RX channel.

This function returns the current state of the Ethernet channel specified by channel. The channel identifier can correspond to either a TX or RX channel; the function determines the direction and returns the associated hal_eth_channel_state_t value from the handle.

The function:

Validates heth and channel (with debug and optional runtime checks).
If channel matches any TX channel bit (HAL_ETH_TX_CHANNEL_ALL), it derives the TX channel index and returns heth->tx_channels[index].channel_state.
Otherwise, it derives the RX channel index and returns heth->rx_channels[index].channel_state.
On any error (invalid index, parameter check failure), it returns HAL_ETH_CHANNEL_STATE_RESET.

Note

If channel contains multiple channel bits, the first matching channel (lowest index) is used.

Note

If parameter checking is enabled and heth is NULL or channel is invalid, the function returns HAL_ETH_CHANNEL_STATE_RESET.

Parameters :

heth – [in] Pointer to a constant hal_eth_handle_t structure that holds the Ethernet configuration and channel runtime states.
channel – [in] Channel identifier (bitmask) selecting the desired TX or RX channel. Must satisfy IS_ETH_CHANNEL_INDEX. If the bitmask intersects HAL_ETH_TX_CHANNEL_ALL, a TX channel state is returned; otherwise an RX channel state is returned.

Return values :

hal_eth_channel_state_t – The current state of the selected channel, typically one of:

HAL_ETH_CHANNEL_STATE_RESET
HAL_ETH_CHANNEL_STATE_CONFIGURED
HAL_ETH_CHANNEL_STATE_ACTIVE
HAL_ETH_CHANNEL_STATE_SUSPENDED (Actual values depend on the hal_eth_channel_state_t enum.)

uint32_t HAL_ETH_GetLastErrorCodes ( const hal_eth_handle_t * heth ) ¶

Retrieve the last recorded Ethernet error codes.

This function returns the content of the last_error_codes field of the given Ethernet handle heth. The field is typically updated internally by the HAL when errors occur on the Ethernet peripheral (e.g. DMA errors, descriptor errors, protocol errors).

Note

This API is available only when USE_HAL_ETH_GET_LAST_ERRORS is defined and set to 1.

Note

The last_error_codes field is read-only from the user point of view and is updated by the HAL internal error handling logic.

Parameters :

heth – [in] Pointer to a constant hal_eth_handle_t structure that contains the runtime state of the Ethernet peripheral, including the last_error_codes field.

Return values :

uint32_t – Bitmask containing the last error codes recorded for this handle. The exact meaning of each bit depends on the Ethernet HAL error definitions (e.g. HAL_ETH_ERROR_xxx).
HAL_INVALID_PARAM – If heth is NULL and parameter checking is enabled (USE_HAL_CHECK_PARAM == 1).

MDIO control and PHY I/O operations functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Exported_Functions_Group12

This subsection provides the Ethernet MDIO Control and PHY I/O Operations Functions.

HAL_ETH_MDIO_UpdateClockRange(): Update the MDIO clock range.
HAL_ETH_MDIO_SetOpAttributes(): Configures Ethernet MDIO command attributes.
HAL_ETH_MDIO_C22ReadData(): Read a register from an external PHY using Clause 22 method.
HAL_ETH_MDIO_C22WriteData(): Write data to an external RHY register using Clause 22 method.
HAL_ETH_MDIO_C45ReadData(): Read a register from an external PHY using Clause 45 method.
HAL_ETH_MDIO_C45WriteData(): Write data to an external RHY register using Clause 45 method.
HAL_ETH_MDIO_C45ReadDataRange(): Read a range of registers from an external PHY using Clause 45 method.

Functions

void HAL_ETH_MDIO_UpdateClockRange ( hal_eth_handle_t * heth ) ¶

Update the MDIO clock range according to the current HCLK frequency.

This function recalculates and updates the MDIO clock divider (CSR Clock Range) in the MACMDIOAR register based on the current AHB bus (HCLK) frequency returned by HAL_RCC_GetHCLKFreq().

It:

Reads the current MACMDIOAR register value.
Clears the CSR Clock Range (CR) bits.
Computes the appropriate divider (e.g. ETH_MDC_CLK_DIV_16, ETH_MDC_CLK_DIV_26, etc.) according to the HCLK range.
Writes back the new value into MACMDIOAR.

The mapping between HCLK frequency and divider is:

hclk < 35 MHz –> ETH_MDC_CLK_DIV_16
35 MHz <= hclk < 60 MHz –> ETH_MDC_CLK_DIV_26
60 MHz <= hclk < 100 MHz –> ETH_MDC_CLK_DIV_42
100 MHz <= hclk < 150 MHz –> ETH_MDC_CLK_DIV_62
150 MHz <= hclk < 250 MHz –> ETH_MDC_CLK_DIV_102
250 MHz <= hclk < 300 MHz –> ETH_MDC_CLK_DIV_124
300 MHz <= hclk < 500 MHz –> ETH_MDC_CLK_DIV_204
hclk >= 500 MHz –> ETH_MDC_CLK_DIV_324

Note

This function is similar in purpose to the internal helper used during initialization, but can be called at runtime if the HCLK configuration changes (e.g. change of system clock).

Note

The MDIO clock must respect the maximum clock allowed by the PHY (typically around 2.5 MHz); this function selects a divider that ensures compliance based on HCLK.

Note

It is strongly recommended to call this function immediately after any change to the system clock tree that affects HCLK, before performing further MDIO transactions, to avoid violating the external device or the Ethernet MAC maximum MDC clock specification.

Parameters :: heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration information for the Ethernet peripheral.

void HAL_ETH_MDIO_SetOpAttributes ( hal_eth_handle_t * heth , uint32_t cmd_attributes ) ¶

Configure MDIO operation attributes in the MACMDIOAR register.

This function sets specific MDIO operation attributes for subsequent Clause 22/45 MDIO transactions by updating the corresponding bits in the MACMDIOAR register.

MDIO read/write operations performed by the HAL are synchronous: the calling context is blocked until the corresponding MDIO transaction has fully completed on the bus, or until the ETH_MDIO_BUS_TIMEOUT duration is reached.

The attributes updated are:

HAL_ETH_MDIO_FEAT_PSE : Preamble Suppression Enable.
HAL_ETH_MDIO_FEAT_BTB : Back-to-Back transaction mode.
HAL_ETH_MDIO_NTC_1_CYCLE : 1 Trailing clock cycle.
HAL_ETH_MDIO_NTC_2_CYCLES : 2 Trailing clock cycles.
HAL_ETH_MDIO_NTC_3_CYCLES : 3 Trailing clock cycles.
HAL_ETH_MDIO_NTC_4_CYCLES : 4 Trailing clock cycles.
HAL_ETH_MDIO_NTC_5_CYCLES : 5 Trailing clock cycles.
HAL_ETH_MDIO_NTC_6_CYCLES : 6 Trailing clock cycles.
HAL_ETH_MDIO_NTC_7_CYCLES : 7 Trailing clock cycles.

The caller provides cmd_attributes, which must contain the desired combination of these bits (and only these bits). The function then updates MACMDIOAR accordingly.

Note

This function does not start any MDIO transaction; it only configures the attributes used by subsequent MDIO read/write operations.

Note

The caller must ensure that heth is valid and that the Ethernet peripheral has been initialized before calling this function.

Note

IMPORTANT: When performing a complete / full configuration or update sequence of an external device over MDIO, the user must ensure that the whole MDIO transaction sequence is executed in a protected, non-interleaved way. In particular, it must not be interrupted or interleaved with other MDIO accesses targeting the same or any other device on the MDIO bus. This protection must be implemented at the upper (application) level, typically by using a mutual exclusion or equivalent locking mechanism around the full MDIO access sequence.

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration information for the Ethernet peripheral.
cmd_attributes – [in] Bitmask of MDIO operation attributes to be applied. This value is typically composed of one or more of:
- HAL_ETH_MDIO_FEAT_PSE : Preamble Suppression Enable.
- HAL_ETH_MDIO_FEAT_BTB : Back-to-Back transaction mode.
- HAL_ETH_MDIO_NTC_1_CYCLE : 1 Trailing clock cycle.
- HAL_ETH_MDIO_NTC_2_CYCLES : 2 Trailing clock cycles.
- HAL_ETH_MDIO_NTC_3_CYCLES : 3 Trailing clock cycles.
- HAL_ETH_MDIO_NTC_4_CYCLES : 4 Trailing clock cycles.
- HAL_ETH_MDIO_NTC_5_CYCLES : 5 Trailing clock cycles.
- HAL_ETH_MDIO_NTC_6_CYCLES : 6 Trailing clock cycles.
- HAL_ETH_MDIO_NTC_7_CYCLES : 7 Trailing clock cycles.

hal_status_t HAL_ETH_MDIO_C22WriteData ( const hal_eth_handle_t * heth , uint8_t phy_dev_addr , uint8_t reg_addr , uint16_t data ) ¶

Write a single PHY register using MDIO Clause 22.

This function performs one Clause 22 MDIO write operation to the register reg_addr of the PHY device phy_dev_addr, writing the 16-bit value data.

MDIO write operations performed by the HAL are synchronous: the calling context is blocked until the corresponding MDIO transaction has fully completed on the bus, or until the ETH_MDIO_BUS_TIMEOUT duration is reached.

The procedure is:

Check that the MDIO controller is not busy.
Disable Clause 45 mode (enable Clause 22) by clearing MACMDIOAR C45E bit.
Load the data to be written into MACMDIODR (DATA field).
Load MACMDIOAR with:
- PHY address (phy_dev_addr),
- Register address (reg_addr),
- Write command (ETH_GOC_OPERATION_WRITE).
Set the ETH_MACMDIOAR_BUSY bit to start the write operation.
Poll on ETH_MACMDIOAR_BUSY until cleared or until ETH_MDIO_BUS_TIMEOUT elapses.

See also

HAL_ETH_MDIO_C22ReadData

See also

HAL_ETH_MDIO_C45WriteData

Note

Clause 22 mode is selected by clearing MACMDIOAR C45E bit.

Note

Parameters :

heth – [in] Pointer to a constant hal_eth_handle_t structure that contains the configuration information for the Ethernet peripheral. The handle itself is not modified by this function.
phy_dev_addr – [in] PHY device address on the MDIO bus (Clause 22 PHY address).
reg_addr – [in] Register address (0..31) within the selected PHY device.
data – [in] 16-bit data value to write into the specified register.

Return values :

HAL_OK – The register has been successfully written.
HAL_ERROR –
- The MDIO controller was busy at the beginning of the operation.
- A timeout occurred while waiting for the ETH_MACMDIOAR_BUSY flag to clear.
HAL_INVALID_PARAM – The heth parameter is NULL (only when parameter checking is enabled via USE_HAL_CHECK_PARAM).

hal_status_t HAL_ETH_MDIO_C22ReadData ( hal_eth_handle_t * heth , uint8_t phy_dev_addr , uint8_t reg_addr , uint16_t * p_data ) ¶

Read a single PHY register using MDIO Clause 22.

This function performs one Clause 22 MDIO read operation of the register reg_addr located in the specified PHY device phy_dev_addr, and returns the 16-bit register content through p_data.

MDIO read operations performed by the HAL are synchronous: the calling context is blocked until the corresponding MDIO transaction has fully completed on the bus, or until the ETH_MDIO_BUS_TIMEOUT duration is reached.

The procedure is:

Check that the MDIO controller is not busy.
Disable Clause 45 mode (enable Clause 22) by clearing MACMDIOAR C45E bit.
Load MACMDIOAR with:
- PHY address (phy_dev_addr),
- Register address (reg_addr),
- Read command (ETH_GOC_OPERATION_READ).
Set the ETH_MACMDIOAR_BUSY bit to start the read operation.
Poll on ETH_MACMDIOAR_BUSY until cleared or until ETH_MDIO_BUS_TIMEOUT elapses.
Read the data from MACMDIODR into p_data.

See also

HAL_ETH_MDIO_C22WriteData

See also

HAL_ETH_MDIO_C45ReadData

Note

Clause 22 mode is selected by clearing MACMDIOAR C45E bit.

Note

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration information for the Ethernet peripheral.
phy_dev_addr – [in] PHY device address on the MDIO bus (Clause 22 PHY address).
reg_addr – [in] Register address (0..31) within the selected PHY device.
p_data – [out] Pointer to a uint16_t variable where the read register value will be stored.

Return values :

HAL_OK – The register has been successfully read and *p_data updated.
HAL_ERROR –
- The MDIO controller was busy at the beginning of the operation.
- A timeout occurred while waiting for the ETH_MACMDIOAR_BUSY flag to clear.
HAL_INVALID_PARAM – heth or p_data is NULL (only when parameter checking is enabled via USE_HAL_CHECK_PARAM).

hal_status_t HAL_ETH_MDIO_C45WriteData ( const hal_eth_handle_t * heth , uint8_t phy_addr , uint8_t dev_addr , uint16_t reg_addr , uint16_t data ) ¶

Write a single PHY register using MDIO Clause 45.

This function performs one Clause 45 MDIO write operation to the register reg_addr located in the specified PHY device ( phy_addr, dev_addr), writing the 16-bit value data.

The procedure is:

Check that the MDIO controller is not busy.
Enable Clause 45 access in MACMDIOAR.
Program the target register address into MACMDIODR (RA field).
Program the data to be written into MACMDIODR (DATA field).
Configure MACMDIOAR with:
- PHY address (phy_addr),
- Device (MMD) address (dev_addr),
- Write command (ETH_GOC_OPERATION_WRITE).
Set the ETH_MACMDIOAR_BUSY bit to start the write.
Poll on ETH_MACMDIOAR_BUSY until cleared or until ETH_MDIO_BUS_TIMEOUT elapses.

See also

HAL_ETH_MDIO_C45ReadData

See also

HAL_ETH_MDIO_C45ReadDataRange

Note

Clause 45 mode is enabled during this function through the MACMDIOAR C45E bit.

Note

Parameters :

heth – [in] Pointer to a constant hal_eth_handle_t structure that contains the configuration information for the Ethernet peripheral. The handle itself is not modified by this function.
phy_addr – [in] PHY address on the MDIO bus (Clause 45 PHY address field).
dev_addr – [in] PHY device (MMD) address for Clause 45 access.
reg_addr – [in] Register address (within the selected device) to be written.
data – [in] 16-bit data value to write into the specified register.

Return values :

HAL_OK – The register has been successfully written.
HAL_ERROR –
- The MDIO controller was busy at the beginning of the operation.
- A timeout occurred while waiting for the ETH_MACMDIOAR_BUSY flag to clear.
HAL_INVALID_PARAM – The heth parameter is NULL (only when parameter checking is enabled via USE_HAL_CHECK_PARAM).

hal_status_t HAL_ETH_MDIO_C45ReadData ( hal_eth_handle_t * heth , uint8_t phy_addr , uint8_t dev_addr , uint16_t reg_addr , uint16_t * p_data ) ¶

Read a single PHY register using MDIO Clause 45.

This function performs one Clause 45 MDIO read operation of the register reg_addr located in the specified PHY device ( phy_addr, dev_addr), and returns the 16-bit register content through p_data.

The procedure is:

Check that the MDIO controller is not busy.
Enable Clause 45 access in MACMDIOAR.
Program the target register address into MACMDIODR.
Configure MACMDIOAR with:
- PHY address (phy_addr),
- Device (MMD) address (dev_addr),
- Read command (ETH_GOC_OPERATION_READ).
Set the ETH_MACMDIOAR_BUSY bit to start the read.
Poll on ETH_MACMDIOAR_BUSY until cleared or until ETH_MDIO_BUS_TIMEOUT elapses.
Read the data from MACMDIODR into p_data.

See also

HAL_ETH_MDIO_C45ReadDataRange

Note

Clause 45 mode is enabled during this function through the MACMDIOAR C45E bit.

Note

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration information for the Ethernet peripheral.
phy_addr – [in] PHY address on the MDIO bus (Clause 45 PHY address field).
dev_addr – [in] PHY device (MMD) address for Clause 45 access.
reg_addr – [in] Register address (within the selected device) to be read.
p_data – [out] Pointer to a uint16_t variable where the read register value will be stored.

Return values :

HAL_OK – The register has been successfully read and *p_data updated.
HAL_ERROR –
- The MDIO controller was busy at the beginning of the operation.
- A timeout occurred while waiting for the ETH_MACMDIOAR_BUSY flag to clear.
HAL_INVALID_PARAM – The heth parameter is NULL (only when parameter checking is enabled via USE_HAL_CHECK_PARAM).

hal_status_t HAL_ETH_MDIO_C45ReadDataRange ( hal_eth_handle_t * heth , uint8_t phy_addr , uint8_t dev_addr , uint16_t start_reg_addr , uint16_t * p_data , uint16_t count ) ¶

Read a range of PHY registers using MDIO Clause 45 post-increment access.

This function performs a sequence of Clause 45 MDIO read operations starting from start_reg_addr and reads count consecutive registers into the buffer pointed to by p_data.

The procedure is:

Check that the MDIO controller is not busy.
Enable Clause 45 access in MACMDIOAR.
Configure MACMDIOAR with:
- PHY address (phy_addr),
- Device address (dev_addr),
- Post-read increment access command (ETH_GOC_OPERATION_PRIAC45).
Program the starting register address in MACMDIODR.
For each element to read:
- Set the ETH_MACMDIOAR_BUSY bit to start a post-increment read.
- Wait for the ETH_MACMDIOAR_BUSY bit to clear or until ETH_MDIO_BUS_TIMEOUT elapses.
- Read the data from MACMDIODR into p_data[index].

Note

Clause 45 mode is enabled for the duration of this function through the MACMDIOAR C45E bit.

Note

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration information for the Ethernet peripheral.
phy_addr – [in] PHY address on the MDIO bus (Clause 45 PHY address field).
dev_addr – [in] PHY device (MMD) address for Clause 45 access.
start_reg_addr – [in] First PHY register address to read (Clause 45 register address).
p_data – [out] Pointer to a buffer of uint16_t where the received register values will be stored. Must have room for count entries.
count – [in] Number of consecutive registers to read starting from start_reg_addr.

Return values :

HAL_OK – All requested registers have been successfully read.
HAL_ERROR –
- The MDIO controller was busy at the beginning of the operation.
- A timeout occurred while waiting for the ETH_MACMDIOAR_BUSY flag to clear for any of the read operations.
HAL_INVALID_PARAM – heth or p_data is NULL (only when parameter checking is enabled via USE_HAL_CHECK_PARAM).

bus operation functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Exported_Functions_Group13

This subsection provides the Ethernet Bus Operation Function.

HAL_ETH_AcquireBus(): Acquire the Ethernet bus.
HAL_ETH_ReleaseBus(): Release the Ethernet bus.

Functions

hal_status_t HAL_ETH_AcquireBus ( hal_eth_handle_t * heth , uint32_t timeout_ms ) ¶

Acquire exclusive access to the Ethernet bus (semaphore take).

This function attempts to take the OS semaphore associated with the Ethernet handle, in order to gain exclusive access to the Ethernet peripheral (bus protection / mutual exclusion).

The function:

Verifies that heth is not NULL (with debug and optional runtime checks).
Calls HAL_OS_SemaphoreTake() on heth->semaphore with the given timeout.
Returns HAL_OK if the semaphore is successfully taken, or HAL_ERROR otherwise (e.g. timeout, OS error).

See also

HAL_ETH_ReleaseBus

Note

The caller must ensure that the Ethernet handle heth has been properly initialized and its semaphore member correctly created.

Note

This function does not modify the hardware state of the Ethernet peripheral; it only manages synchronization via an OS semaphore.

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the Ethernet configuration and the OS semaphore used for bus protection.
timeout_ms – [in] Timeout value in milliseconds for acquiring the semaphore. The special values (e.g. blocking forever) depend on the underlying OS implementation of HAL_OS_SemaphoreTake.

Return values :

HAL_OK – The bus semaphore was successfully acquired within timeout_ms.
HAL_ERROR – The semaphore could not be acquired (e.g. timeout occurred or OS reported an error).
HAL_INVALID_PARAM – The heth parameter is NULL (only when parameter checking is enabled via USE_HAL_CHECK_PARAM).

hal_status_t HAL_ETH_ReleaseBus ( hal_eth_handle_t * heth ) ¶

Release the Ethernet bus access semaphore.

This function releases the OS semaphore associated with the Ethernet handle, allowing other tasks/contexts to acquire the bus. It is typically used to unlock access to the Ethernet peripheral after a protected operation is completed.

The function:

Verifies that heth is not NULL (with debug and optional runtime checks).
Calls HAL_OS_SemaphoreRelease() on heth->semaphore.
Returns HAL_OK if the semaphore release succeeds, or HAL_ERROR otherwise.

See also

HAL_ETH_AcquireBus

Note

The caller must ensure that the Ethernet handle heth has been properly initialized and its semaphore member correctly created.

Note

This function does not change the hardware state of the Ethernet peripheral; it only manages synchronization via an OS semaphore.

Parameters :

heth – [in] Pointer to an hal_eth_handle_t structure that contains the Ethernet configuration and the OS semaphore used for bus protection.

Return values :

HAL_OK – The bus semaphore was successfully released.
HAL_ERROR – Error while releasing the semaphore (e.g. OS call failed).
HAL_INVALID_PARAM – The heth parameter is NULL (only when parameter checking is enabled via USE_HAL_CHECK_PARAM).

user data functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Exported_Functions_Group14

This subsection provides the Ethernet User Data Functions.

HAL_ETH_SetUserData(): Set user data pointer.
HAL_ETH_GetUserData(): Get user data pointer.

Functions

void HAL_ETH_SetUserData ( hal_eth_handle_t * heth , const void * p_user_data ) ¶

Set the user data pointer.

This function associates an opaque user data pointer with the specified Ethernet handle. The HAL does not interpret or modify the user data; it is provided for application use (for example, to store context or state information related to the Ethernet instance).

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
p_user_data – [in] Pointer to user data to be associated with the Ethernet handle. This pointer can be NULL.

Pre :

heth must not be NULL.

const void * HAL_ETH_GetUserData ( const hal_eth_handle_t * heth ) ¶

Get the user data pointer.

This function returns the user data pointer previously associated with the specified Ethernet handle via HAL_ETH_SetUserData.

Parameters :: heth – [in] Pointer to a hal_eth_handle_t structure that contains the configuration information for the specified Ethernet peripheral.
Return values :: Pointer – to user data associated with the Ethernet handle, or NULL if no user data has been set.
Pre :: heth must not be NULL.

ETH external WAKEUP management functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Exported_Functions_Group15

Functions

void HAL_ETH_WAKEUP_EnableIT ( void ) ¶

Enable the Ethernet Wakeup External interrupt.

This function enables the interrupt request for the Ethernet Wakeup External line by setting the corresponding bit in the External Interrupt Mask Register 2 (IMR2). It uses an atomic operation to ensure thread safety.

Note

This function is typically used to allow the Ethernet peripheral to wake up the MCU from low-power modes via an external interrupt.

Note

To disable the interrupt, use HAL_ETH_WAKEUP_DisableIT.

void HAL_ETH_WAKEUP_DisableIT ( void ) ¶

Disable the Ethernet Wakeup External interrupt.

This function disables the interrupt request for the Ethernet Wakeup External line by clearing the corresponding bit in the External Interrupt Mask Register 2 (IMR2).

Note

To enable the interrupt, use HAL_ETH_WAKEUP_EnableIT.

hal_eth_wakeup_trigger_t HAL_ETH_WAKEUP_GetPendingIT ( void ) ¶

Get the interrupt pending bit for the Ethernet Wakeup External line.

This function checks the External Rising Pending Register 2 (RPR2) and Falling Pending Register 2 (FPR2) to determine which edge(s) have triggered a pending interrupt for the Ethernet Wakeup External line.

Note

The function returns one of the following values:

HAL_ETH_WAKEUP_TRIGGER_NONE: No pending trigger.
HAL_ETH_WAKEUP_TRIGGER_RISING: Rising edge trigger is pending.
HAL_ETH_WAKEUP_TRIGGER_FALLING: Falling edge trigger is pending.
HAL_ETH_WAKEUP_TRIGGER_RISING_FALLING: Both rising and falling edge triggers are pending.

Return values :: hal_eth_wakeup_trigger_t – The pending trigger flag(s) for the Ethernet Wakeup External line.

void HAL_ETH_WAKEUP_ClearPendingIT ( hal_eth_wakeup_trigger_t edge ) ¶

Clear the pending interrupt flag(s) for the Ethernet Wakeup External line.

This function clears the pending interrupt flag(s) for the Ethernet Wakeup External line based on the specified edge(s). It writes to the External Rising Pending Register 2 (RPR2) and/or Falling Pending Register 2 (FPR2) to clear the corresponding pending bits.

Parameters :

edge – Specifies which edge(s) to clear pending flags for. This parameter can be one or a combination of the following values:

HAL_ETH_WAKEUP_TRIGGER_RISING: Clear rising edge pending flag.
HAL_ETH_WAKEUP_TRIGGER_FALLING: Clear falling edge pending flag.
HAL_ETH_WAKEUP_TRIGGER_RISING_FALLING: Clear both rising and falling edge pending flags.

void HAL_ETH_WAKEUP_EnableTrigger ( hal_eth_wakeup_trigger_t edge ) ¶

Enable trigger edge(s) for the Ethernet Wakeup External line.

This function enables the specified edge trigger(s) for the Ethernet Wakeup External line by setting the corresponding bits in the External Rising Trigger Selection Register 2 (RTSR2) and/or Falling Trigger Selection Register 2 (FTSR2). It also clears the rising edge pending bit when enabling the rising edge trigger.

Note

To disable trigger edge(s), use HAL_ETH_WAKEUP_DisableTrigger.

Parameters :

edge – Specifies which edge(s) to enable as triggers. This parameter can be one or a combination of the following values:

HAL_ETH_WAKEUP_TRIGGER_RISING: Enable rising edge trigger.
HAL_ETH_WAKEUP_TRIGGER_FALLING: Enable falling edge trigger.
HAL_ETH_WAKEUP_TRIGGER_RISING_FALLING: Enable both rising and falling edge triggers.

void HAL_ETH_WAKEUP_DisableTrigger ( hal_eth_wakeup_trigger_t edge ) ¶

Disable trigger edge(s) for the Ethernet Wakeup External line.

This function disables the specified edge trigger(s) for the Ethernet Wakeup External line by clearing the corresponding bits in the External Rising Trigger Selection Register 2 (RTSR2) and/or Falling Trigger Selection Register 2 (FTSR2).

Note

To enable trigger edge(s), use HAL_ETH_WAKEUP_EnableTrigger.

Parameters :

edge – Specifies which edge(s) to disable as triggers. This parameter can be one or a combination of the following values:

HAL_ETH_WAKEUP_TRIGGER_RISING: Disable rising edge trigger.
HAL_ETH_WAKEUP_TRIGGER_FALLING: Disable falling edge trigger.
HAL_ETH_WAKEUP_TRIGGER_RISING_FALLING: Disable both rising and falling edge triggers.

void HAL_ETH_WAKEUP_GenerateSWIT ( void ) ¶

Generate a software interrupt for the Ethernet Wakeup External line.

This function generates a software interrupt request for the Ethernet Wakeup External line by setting the corresponding bit in the External Software Interrupt Event Register 2 (SWIER2). This can be used to simulate an external interrupt event in software, which is useful for testing or triggering interrupt handlers manually.

Note

The software interrupt will be handled in the same way as a hardware-generated interrupt for the specified External line.

ETH Private Functions ¶

Note

This section is not available for STM32C562xx.

group ETH_Private_Functions

Functions

void ETH_MAC_SetConfigDefault ( struct hal_eth_handle_s * heth ) ¶

Initialize MAC registers with driver default values.

Parameters :: heth – Pointer to a hal_eth_handle_t structure which contains the ETH instance.

void ETH_MAC_SetConfig ( const hal_eth_handle_t * heth , const hal_eth_mac_config_t * p_mac_conf ) ¶

Apply MAC configuration to hardware registers.

Parameters :

heth – Pointer to a hal_eth_handle_t structure which contains the ETH instance.
p_mac_conf – Pointer to a hal_eth_mac_config_t structure containing MAC settings.

void ETH_SetMDIOClockRange ( hal_eth_handle_t * heth ) ¶

Configure the MDIO clock range according to the AHB bus (HCLK) frequency.

This static helper sets the MDIO clock divider in the MACMDIOAR register so that the resulting MDIO clock stays within the valid range for the Ethernet PHY.

The function:

Reads the current MACMDIOAR register value.
Clears the CSR Clock Range (CR) bits.
Retrieves the current HCLK frequency via HAL_RCC_GetHCLKFreq().
Selects the appropriate divider (e.g. ETH_MDC_CLK_DIV_16, ETH_MDC_CLK_DIV_26, …) depending on the HCLK range.
Writes back the updated value to MACMDIOAR.

The mapping between HCLK frequency and divider is:

hclk < 35 MHz –> ETH_MDC_CLK_DIV_16
35 MHz <= hclk < 60 MHz –> ETH_MDC_CLK_DIV_26
60 MHz <= hclk < 100 MHz –> ETH_MDC_CLK_DIV_42
100 MHz <= hclk < 150 MHz –> ETH_MDC_CLK_DIV_62
150 MHz <= hclk < 250 MHz –> ETH_MDC_CLK_DIV_102
250 MHz <= hclk < 300 MHz –> ETH_MDC_CLK_DIV_124
300 MHz <= hclk < 500 MHz –> ETH_MDC_CLK_DIV_204
hclk >= 500 MHz –> ETH_MDC_CLK_DIV_324

Note

The MDIO clock must not exceed the maximum frequency specified in the PHY datasheet (typically around 2.5 MHz). This function chooses the divider to satisfy that requirement based on HCLK.

Note

The caller must ensure that heth is valid and that the Ethernet peripheral clock configuration is already set.

Parameters :: heth – [in] Pointer to an hal_eth_handle_t structure that contains the configuration information for the Ethernet peripheral.

uint32_t ETH_GetMDIOClockRange ( uint32_t eth_hclk_freq ) ¶

Get the MDIO clock range (ETH_MACMDIOAR.CR) for a given HCLK frequency.

Computes the CSR clock range field (CR) that configures the MDC frequency derived from the system HCLK. The selected configuration targets the highest possible MDC frequency within the allowed bounds [ETH_MDC_CLK_MIN_HZ .. ETH_MDC_CLK_MAX_HZ].

Parameters :: eth_hclk_freq – HCLK frequency in Hz.
Return values :: MDIO – CSR clock range encoding to be OR-ed into ETH_MACMDIOAR.

void ETH_MTL_SetConfigDefault ( struct hal_eth_handle_s * heth ) ¶

Initialize MTL registers with driver default values.

Parameters :: heth – Pointer to a hal_eth_handle_t structure which contains the ETH instance.

void ETH_MTL_SetConfig ( hal_eth_handle_t * heth , const hal_eth_mtl_config_t * p_mtl_conf ) ¶

Apply MTL configuration to hardware registers.

Parameters :

heth – Pointer to a hal_eth_handle_t structure which contains the ETH instance.
p_mtl_conf – Pointer to a hal_eth_mtl_config_t structure containing MTL settings.

void ETH_DMA_SetConfigDefault ( struct hal_eth_handle_s * heth ) ¶

Initialize DMA registers with driver default values.

Parameters :: heth – Pointer to a hal_eth_handle_t structure which contains the ETH instance.

void ETH_DMA_SetConfig ( hal_eth_handle_t * heth , const hal_eth_dma_config_t * p_dma_conf ) ¶

Apply DMA configuration to hardware registers.

Parameters :

heth – Pointer to a hal_eth_handle_t structure which contains the ETH instance.
p_dma_conf – Pointer to a hal_eth_dma_config_t structure containing DMA settings.

void ETH_InitCommonCallbacksToDefault ( hal_eth_handle_t * heth ) ¶

Initialize the callbacks to their default values.

Parameters :: heth – Pointer to a hal_eth_handle_t structure which contains the ETH instance.

void ETH_InitTxCallbacksToDefault ( hal_eth_tx_channel_handle_t * hchannel ) ¶

Initialize the Tx channel callbacks to their default values.

Parameters :: hchannel – Pointer to a hal_eth_tx_channel_handle_t structure which contains the Tx channel instance.

void ETH_InitRxCallbacksToDefault ( hal_eth_rx_channel_handle_t * hchannel ) ¶

Initialize the Rx channel callbacks to their default values.

Parameters :: hchannel – Pointer to a hal_eth_rx_channel_handle_t structure which contains the Rx channel instance.

void ETH_SetTxChannelDefaultConfig ( hal_eth_handle_t * heth , uint32_t channel ) ¶

Initialize a Tx channel with default DMA and MTL settings.

Parameters :

heth – Pointer to a hal_eth_handle_t structure which contains the ETH instance.
channel – Channel index (zero-based)

void ETH_DMA_SetConfigTxChannel ( const hal_eth_handle_t * heth , uint32_t ch , const hal_eth_dma_tx_channel_config_t * p_dma_tx_ch_conf ) ¶

Configure DMA registers for a Tx channel.

Parameters :

heth – Pointer to a hal_eth_handle_t structure which contains the ETH instance.
ch – Channel index (zero-based)
p_dma_tx_ch_conf – Pointer to hal_eth_dma_tx_channel_config_t containing channel DMA settings.

void ETH_GetDMATxChannelConfig ( const hal_eth_handle_t * heth , uint32_t ch , hal_eth_dma_tx_channel_config_t * p_dma_tx_ch_conf ) ¶

Retrieve current DMA Tx channel configuration from hardware registers.

Parameters :

heth – Pointer to a hal_eth_handle_t structure (ETH handle)
ch – Channel index
p_dma_tx_ch_conf – Pointer to a hal_eth_dma_tx_channel_config_t structure to fill

void ETH_MTL_SetConfigTxChannel ( const hal_eth_handle_t * heth , uint32_t ch , const hal_eth_mtl_tx_queue_config_t * p_mtl_tx_q_conf ) ¶

Configure MTL registers for a Tx queue.

Parameters :

heth – Pointer to a hal_eth_handle_t structure which contains the ETH instance.
ch – Queue index (zero-based)
p_mtl_tx_q_conf – Pointer to hal_eth_mtl_tx_queue_config_t containing queue settings.

void ETH_GetMtlTxChannelConfig ( const hal_eth_handle_t * heth , uint32_t ch , hal_eth_mtl_tx_queue_config_t * p_mtl_tx_q_conf ) ¶

Retrieve current MTL Tx queue configuration from hardware registers.

Parameters :

heth – Pointer to a hal_eth_handle_t structure (ETH handle)
ch – Queue index
p_mtl_tx_q_conf – Pointer to a hal_eth_mtl_tx_queue_config_t structure to fill

hal_status_t ETH_RequestTxDMA ( hal_eth_handle_t * heth , uint32_t ch , hal_eth_buffer_t * p_eth_buffer , uint32_t buffer_count , hal_eth_tx_pkt_config_t * p_tx_conf ) ¶

Request and program DMA descriptors for a TX packet.

Prepares one or more DMA TX descriptors for the provided packet buffers and notifies the DMA engine to start transmission.

Parameters :

heth – Pointer to HAL ETH handle
ch – TX channel index (zero-based)
p_eth_buffer – Pointer to an array of buffer descriptors containing data pointers and lengths
buffer_count – Number of buffers in p_eth_buffer
p_tx_conf – Pointer to TX packet configuration (VLAN/CSUM/notify etc.)

Return values :

HAL_OK – Descriptors programmed and DMA notified successfully
HAL_BUSY – Not enough free descriptors available to queue the packet

uint32_t ETH_ExecTxDataHandler ( hal_eth_handle_t * heth , uint32_t ch ) ¶

Execute the TX data handler for a channel.

This routine walks the TX descriptor ring of the selected channel and processes the descriptors that are no longer owned by the DMA engine. For each available descriptor:

If it corresponds to a context/auxiliary descriptor (no packet address), it is reset.
Otherwise, the channel TX complete callback is invoked with the transmitted packet address and status/error information, then the descriptor is reset.

Cache maintenance is performed on the descriptor before it is inspected, using the registered cache invalidate callback.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure.
ch – [in] Zero-based TX channel index.

Return values :

0UL – Processing completed for this channel.
HAL_ETH_TX_CHANNEL_ID – Processing of the TX channel was stopped because the TX complete callback execution failed; the channel can be processed again later.

hal_status_t ETH_StartTxChannel ( hal_eth_handle_t * heth , uint32_t ch , uint32_t * p_desc_mem , uint32_t desc_size_byte ) ¶

Initialize and start a Tx DMA channel.

Parameters :

heth – Pointer to a hal_eth_handle_t structure.
ch – Zero-based Tx channel index.
p_desc_mem – Pointer to descriptor memory base address.
desc_size_byte – Total descriptor memory size in bytes.

Return values :

HAL_OK – Channel started successfully.
HAL_INVALID_PARAM – Descriptor memory is smaller than one descriptor length.

void ETH_SetTxFifoEvent ( hal_eth_handle_t * heth , uint32_t ch , eth_dma_descriptor_t * p_dma_tx_desc , hal_eth_tx_pkt_notify_ctrl_t pkt_notify ) ¶

Configure TX descriptor FIFO event (interrupt) conditions.

Depending on the channel FIFO event mode this will set the IOC bit on the descriptor or force an interrupt when the packet requests notification.

Parameters :

heth – Pointer to HAL ETH handle
ch – TX channel index (zero-based)
p_dma_tx_desc – Pointer to the DMA TX descriptor to update
pkt_notify – Packet notification control flags

eth_tx_dma_process_state_t ETH_DMA_GetTxProcessState ( const ETH_TypeDef * p_ethx , uint32_t ch ) ¶

Retrieve Tx DMA process state for a channel.

Parameters :

p_ethx – Pointer to ETH peripheral instance.
ch – Zero-based Tx channel index.

Return values :

eth_tx_dma_process_state_t – Current Tx DMA process state.

void ETH_DMATxDescListInit ( hal_eth_handle_t * heth , uint32_t ch , uint32_t * p_desc_mem , uint32_t total_mem_size_byte ) ¶

Initialize the DMA TX descriptor list for a channel.

Sets the descriptor list address, computes the ring size, resets each descriptor and programs the DMA channel descriptor pointers.

Parameters :

heth – Pointer to HAL ETH handle
ch – TX channel index (zero-based)
p_desc_mem – Pointer to the descriptor memory area
total_mem_size_byte – Size in bytes of the total descriptor memory area

hal_status_t ETH_StopTxChannel ( hal_eth_handle_t * heth , uint32_t ch ) ¶

Stop a Tx DMA channel and flush its transmit queue.

This routine disables the Tx DMA for the specified channel, waits for the corresponding MTL Tx queue to become empty within the configured timeout, then recycles all Tx descriptors. If all Tx channels are stopped after this operation, the MAC transmitter is also disabled.

Parameters :

heth – Pointer to a hal_eth_handle_t structure.
ch – Zero-based Tx channel index.

Return values :

HAL_OK – Channel stopped successfully.
HAL_ERROR – Timeout occurred while flushing the Tx queue.

void ETH_AbortTxChannel ( hal_eth_handle_t * heth , uint32_t ch ) ¶

Abort and reset a Tx DMA channel.

Stops the Tx DMA engine for the specified channel, flushes the MTL transmit queue, recycles all channel descriptors and clears the software descriptor bookkeeping.

Parameters :

heth – Pointer to the HAL ETH handle.
ch – Tx channel identifier

void ETH_RecycleTxDesc ( hal_eth_handle_t * heth , uint32_t ch ) ¶

Recycle TX descriptors and invoke TX complete callbacks.

This function walks the list of built TX descriptors, invokes the channel TX complete callback for each transmitted packet, then resets the descriptor so it can be reused by the DMA engine.

Parameters :

heth – Pointer to HAL ETH handle
ch – TX channel index (zero-based)

void ETH_SetRxChannelDefaultConfig ( hal_eth_handle_t * heth , uint32_t channel ) ¶

Initialize an Rx channel with default DMA and MTL settings.

Parameters :

heth – Pointer to a hal_eth_handle_t structure which contains the ETH instance.
channel – Channel index (zero-based)

void ETH_DMA_SetConfigRxChannel ( hal_eth_handle_t * heth , uint32_t ch , const hal_eth_dma_rx_channel_config_t * p_dma_rx_ch_conf ) ¶

Configure DMA registers for an Rx channel.

Parameters :

heth – Pointer to a hal_eth_handle_t structure which contains the ETH instance.
ch – Channel index (zero-based)
p_dma_rx_ch_conf – Pointer to hal_eth_dma_rx_channel_config_t containing channel DMA settings.

void ETH_GetDMARxChannelConfig ( const hal_eth_handle_t * heth , uint32_t ch , hal_eth_dma_rx_channel_config_t * p_dma_rx_ch_conf ) ¶

Retrieve current DMA Rx channel configuration from hardware registers.

Parameters :

heth – Pointer to a hal_eth_handle_t structure (ETH handle)
ch – Channel index
p_dma_rx_ch_conf – Pointer to a hal_eth_dma_rx_channel_config_t structure to fill

void ETH_MTL_SetConfigRxChannel ( const hal_eth_handle_t * heth , uint32_t ch , const hal_eth_mtl_rx_queue_config_t * p_mtl_rx_q_conf ) ¶

Configure MTL registers for an Rx queue.

Parameters :

heth – Pointer to a hal_eth_handle_t structure which contains the ETH instance.
ch – Queue index (zero-based)
p_mtl_rx_q_conf – Pointer to hal_eth_mtl_rx_queue_config_t containing queue settings.

void ETH_GetMtlRxChannelConfig ( const hal_eth_handle_t * heth , uint32_t ch , hal_eth_mtl_rx_queue_config_t * p_mtl_rx_q_conf ) ¶

Retrieve current MTL Rx queue configuration from hardware registers.

Parameters :

heth – Pointer to a hal_eth_handle_t structure (ETH handle)
ch – Queue index (zero-based)
p_mtl_rx_q_conf – Pointer to a hal_eth_mtl_rx_queue_config_t structure to fill

uint32_t ETH_ExecRxDataHandler ( hal_eth_handle_t * heth , uint32_t ch ) ¶

Execute the RX data handler for a channel.

This routine walks the RX descriptor ring of the selected channel and processes the descriptors that are no longer owned by the DMA engine. For each available descriptor:

If it is a context descriptor, it is cleared.
Otherwise, packet metadata is extracted and the channel RX complete callback is invoked.
The descriptor is then reset and the ring indexes/counters are updated.

Cache maintenance is performed on the descriptor before it is inspected, using the registered cache invalidate callback.

Parameters :

heth – [inout] Pointer to a hal_eth_handle_t structure.
ch – [in] Zero-based RX channel index.

Return values :

0UL – Processing completed for this channel.
HAL_ETH_RX_CHANNEL_ID – Processing of the TX channel was stopped because the TX complete callback execution failed; the channel can be processed again later.

Pre :

The RX channel lock must be held by the caller.

Pre :

The RX channel state must be HAL_ETH_CHANNEL_STATE_ACTIVE or HAL_ETH_CHANNEL_STATE_SUSPENDED.

hal_status_t ETH_StartRxChannel ( hal_eth_handle_t * heth , uint32_t ch , uint32_t * p_desc_mem , uint32_t desc_size_byte ) ¶

Initialize and start an Rx DMA channel.

Parameters :

heth – Pointer to a hal_eth_handle_t structure.
ch – Zero-based Rx channel index.
p_desc_mem – Pointer to descriptor memory base address.
desc_size_byte – Total descriptor memory size in bytes.

Return values :

HAL_OK – Channel started successfully.
HAL_INVALID_PARAM – Descriptor memory is smaller than one descriptor length.

hal_status_t ETH_StopRxChannel ( hal_eth_handle_t * heth , uint32_t ch ) ¶

Stop an Rx DMA channel and disable MAC Rx if applicable.

This routine disables the Rx DMA for the specified channel, recycles all associated Rx descriptors, and if all Rx channels are stopped, it disables the MAC receiver.

Parameters :

heth – Pointer to a hal_eth_handle_t structure.
ch – Zero-based Rx channel index.

Return values :

HAL_OK – Channel stopped successfully.

void ETH_AbortRxChannel ( hal_eth_handle_t * heth , uint32_t ch ) ¶

Abort and reset an Rx DMA channel.

Stops the Rx DMA engine for the specified channel, recycles all channel descriptors and clears the software descriptor bookkeeping.

Parameters :

heth – Pointer to the HAL ETH handle. Must not be NULL.
ch – Rx channel identifier

void ETH_ResetDMADesc ( eth_dma_descriptor_t * p_dma_tx_desc ) ¶

Reset a DMA descriptor to its default state.

This clears descriptor words and backup pointers so the descriptor can be reused by the driver or re-initialized prior to programming for DMA.

Parameters :: p_dma_tx_desc – Pointer to the DMA descriptor to reset

void ETH_UpdateRxDesc ( hal_eth_handle_t * heth , uint32_t ch ) ¶

Update RX descriptor attach application buffers.

Parameters :

heth – Pointer to HAL ETH handle
ch – RX channel index

void ETH_SetRxFifoEvent ( hal_eth_handle_t * heth , uint32_t ch , eth_dma_descriptor_t * p_dma_rx_desc ) ¶

Configure RX descriptor FIFO event (interrupt) conditions.

Depending on the channel FIFO event mode this will set the IOC bit on the descriptor to generate an interrupt on completion or implement cyclic counting behavior.

Parameters :

heth – Pointer to HAL ETH handle
ch – RX channel index (zero-based)
p_dma_rx_desc – Pointer to the DMA RX descriptor to update

void ETH_DMARxDescListInit ( hal_eth_handle_t * heth , uint32_t ch , uint32_t * p_desc_mem , uint32_t total_mem_size_byte ) ¶

Initialize the DMA RX descriptor list for a channel.

Sets the descriptor list address, computes the ring size, resets each descriptor, updates RX descriptors with application buffers and programs the DMA channel descriptor pointers.

Parameters :

heth – Pointer to HAL ETH handle
ch – RX channel index (zero-based)
p_desc_mem – Pointer to the descriptor memory area
total_mem_size_byte – Size in bytes of the total descriptor memory area

void ETH_RecycleRxDesc ( hal_eth_handle_t * heth , uint32_t ch ) ¶

Recycle RX descriptors and invoke RX complete callbacks.

This function walks the list of built RX descriptors, invokes the channel RX complete callback for each received packet (or context), then resets the descriptor so it can be reused by the DMA engine.

Parameters :

heth – Pointer to HAL ETH handle
ch – RX channel index (zero-based)

eth_rx_dma_process_state_t ETH_DMA_GetRxProcessState ( const ETH_TypeDef * p_ethx , uint32_t ch ) ¶

Retrieve Rx DMA process state for a channel.

Parameters :

p_ethx – Pointer to ETH peripheral instance.
ch – Zero-based Rx channel index.

Return values :

eth_rx_dma_process_state_t – Current Rx DMA process state.

hal_status_t ETH_AlignDescSize ( uint32_t app_req_size , uint32_t * p_desc_size ) ¶

Align descriptor size to an application-requested alignment.

Computes the smallest descriptor size, in bytes, that is a multiple of app_req_size and large enough to contain one eth_dma_descriptor_t. The additional padding must not exceed the hardware skip-length capability derived from ETH_DMACCR_DSL.

Parameters :

app_req_size – Requested alignment in bytes. Must be non-zero and a multiple of ETH_BUS_DATA_WIDTH_BYTE.
p_desc_size – Output pointer that receives the aligned descriptor size in bytes

Return values :

HAL_OK – Alignment computed successfully and stored in p_desc_size
HAL_ERROR – Invalid app_req_size or alignment would exceed the DMA skip-length limit.

void ETH_GetTXChIndex ( uint32_t * p_tx_ch , uint32_t channel ) ¶

Retrieve the zero-based TX channel index corresponding to a channel bitmask.

Note

channel parameter must be a single TX channel bitmask of ETH Tx and Rx channel identifiers.

Parameters :

p_tx_ch – Pointer that will receive the channel index (output)
channel – Channel mask containing the selected TX channel bit(s) (input).

void ETH_GetRXChIndex ( uint32_t * p_rx_ch , uint32_t channel ) ¶

Retrieve the zero-based RX channel index corresponding to a channel mask.

Note

channel parameter must be a single RX channel bitmask of ETH Tx and Rx channel identifiers.

Parameters :

p_rx_ch – Pointer that will receive the channel index (output)
channel – Channel mask containing the selected RX channel bit(s) (input).

hal_status_t ETH_LockChannel ( volatile uint32_t * p_channel_lock_state ) ¶

Acquire channel lock (spinlock) for exclusive access.

Attempts to set the lock state to ETH_CHANNEL_STATE_LOCKED. When USE_HAL_ETH_ATOMIC_CHANNEL_LOCK is enabled, atomic exclusive access (LDREX/STREX) and memory barriers are used to protect the update.

Parameters :

p_channel_lock_state – Pointer to the channel lock state variable

Return values :

HAL_OK – Lock acquired.
HAL_BUSY – Lock already held by another context.

void ETH_UnlockChannel ( volatile uint32_t * p_channel_lock_state ) ¶

Release channel lock (spinlock).

Sets the lock state back to ETH_CHANNEL_STATE_UNLOCKED when atomic locking is enabled. When USE_HAL_ETH_ATOMIC_CHANNEL_LOCK is disabled, this function is a no-op.

Parameters :: p_channel_lock_state – Pointer to the channel lock state variable

uint32_t ETH_WakeupGetPendingIT ( void ) ¶

Get the interrupt pending bit for the Ethernet Wakeup External line.

Note

The function returns one of the following values:

LL_EXTI_TRIGGER_NONE: No pending trigger.
LL_EXTI_TRIGGER_RISING: Rising edge trigger is pending.
LL_EXTI_TRIGGER_FALLING: Falling edge trigger is pending.
LL_EXTI_TRIGGER_RISING_FALLING: Both rising and falling edge triggers are pending.

Return values :: hal_eth_wakeup_trigger_t – The pending trigger flag(s) for the Ethernet Wakeup External line.

void ETH_WakeupClearPendingIT ( uint32_t edge ) ¶

Clear the pending interrupt flag(s) for the Ethernet Wakeup External line.

Parameters :

edge – Specifies which edge(s) to clear pending flags for. This parameter can be one or a combination of the following values:

LL_EXTI_TRIGGER_RISING: Clear rising edge pending flag.
LL_EXTI_TRIGGER_FALLING: Clear falling edge pending flag.
LL_EXTI_TRIGGER_RISING_FALLING: Clear both rising and falling edge pending flags.